feat: add shell mode (!) to the CLI (#1079)

* feat: add shell mode (`!`) to the CLI

Add shell mode, letting users run shell commands directly from the prompt
with `!`. Output streams live into the transcript, supports backgrounding
(ctrl+b), cancellation (Esc / Ctrl+C), input queuing while running, and
enters the conversation context with resume support.

* feat(kimi-code): show shell mode label on editor border and add tip

Render a "! shell mode" label on the top-left of the editor border while the editor is in `!` bash mode, so the active mode is visible at a glance. Also add a rotating toolbar tip (`! to run a shell command`) to surface the feature.

* feat(kimi-code): refine shell mode queue, history, and display

- Keep `!` commands out of input history so they never resurface as bare text stripped of their `!`.

- Make `!` commands non-steerable: Ctrl-S skips them (they stay queued to run after the current task) and the steer hint is only shown when something is actually steerable.

- Render queued `!` commands with a `$` prompt and the shell-mode hue so they read as commands, not as text to send to the model.

- Echo executed shell commands with a `$` prompt instead of `!`.

* fix(kimi-code): sanitize shell output and harden rendering

Captured shell command output can contain terminal control sequences (colours, cursor moves, alternate-screen switches, OSC hyperlinks, carriage-return spinners, bells). pi-tui's Text passes strings straight to the terminal, so any unhandled sequence was executed by the terminal and fought with pi-tui's own cursor control, producing the blank-screen-plus-leftover-characters mess after running commands like pnpm dev or a nested TUI.

- Sanitize CSI (incl. private modes), OSC, single-char ESC and C0 control chars (keeping newline and tab) in both the finished/resume view (previously unsanitized) and the running tail.

- Make the sanitize, format, and ShellRunComponent render paths never-throw, and cap the live running buffer, so a misbehaving command cannot crash the TUI.

- Dispose transcript children on clear so ShellRunComponent's timer is released on /clear or session switch.

* fix(kimi-code): render shell command echo with $ instead of sparkles

The shell command echo is a 'user' transcript entry, so UserMessageComponent prefixed it with the USER_MESSAGE_BULLET (sparkles), producing 'sparkles $ command'.

Add an optional bullet override to UserMessageComponent / TranscriptEntry and set it to an empty string for the shell echo (both live and resume), so the '$ command' content sits at the leading column where the sparkles marker used to be. Normal user messages keep the sparkles bullet.

* fix(kimi-code): enter shell mode when pasting a !-prefixed command

The bash-mode trigger only handled the single ! keystroke, so a pasted !cmd was inserted as literal text in prompt mode and submitted as a normal message.

After pi-tui inserts pasted content, detect an empty-prompt buffer that now starts with !, switch to bash mode, and strip the leading ! so the buffer holds only the command, matching the typed ! path.

* fix(kimi-code): restore shell mode when recalling a queued command

recallLastQueued() dropped the queued item's mode, and the Up-arrow recall only restored the text. A queued ! command (queued while another command runs, which resets the editor to prompt mode) therefore came back as a normal prompt and was submitted as a message instead of a shell command.

Return the full QueuedMessage from recallLastQueued() and restore editor.inputMode (plus the onInputModeChange sync) from the recalled item's mode.

* feat(kimi-code): use violet as the shell mode color

Replace the claude-code-style magenta/rose shellMode token with a violet that is distinct from plan-mode blue, the user role amber, success green, error red, and the teal accent.

Custom themes that omit the token fall back to this new default via the base+overrides merge, so existing custom themes keep working unchanged.

* chore: refine the shell mode changeset

* docs: document shell mode

Add a Shell mode section to the interaction guide and list the ! and Ctrl+B shortcuts in the keyboard reference, in both English and Chinese.

* test(protocol): include shell events in volatile classification check

shell.output and shell.started were added as volatile event types for shell mode; update the snapshot test's volatile-type list and count accordingly.

* fix(agent-core): surface shell command failure reason with no output

When a ! shell command fails without producing stdout/stderr (non-zero exit with no output, timeout, spawn failure), the failure reason lived only in the tool result's output and the TUI showed '(no output)'. Fold it into stderr so the live view and replay show what went wrong.

* fix(kimi-code): decode CSI-u ! to enter shell mode

In terminals with the Kitty keyboard protocol (VSCode integrated terminal, Kitty), pressing ! arrives as a CSI-u sequence, so the raw normalized === '!' comparison never matched and shell mode could not be entered by typing !. Decode with printableChar before comparing, matching every other printable-key check in the TUI.

* fix(kimi-code): do not steer while a shell command is running

Ctrl-S steers queued input into the running turn, but a shell command is not an agent turn, so steering during streamingPhase === 'shell' would launch a turn before the command output is recorded. Keep Ctrl-S a no-op during shell runs; queued messages stay queued.

* fix(agent-core): escape bash tag delimiters in shell output

Shell command output is arbitrary text; if it contains a bash tag delimiter such as </bash-stdout>, the recorded pseudo-XML wrapper breaks and replay extracts the wrong slice. Escape the content when wrapping it in agent-core and unescape when extracting during replay, so output survives round-trip intact.

* docs: document the shellMode theme token

The shellMode color token was added to the palette but not propagated to its mirrors. Add it to the custom-theme docs token table, the theme JSON schema, and the custom-theme skill token list.

* feat(agent-core): reset background task deadline on detach

Add a resettable deadline timer to BackgroundManager and let tasks register a detach timeout; when a foreground task is moved to the background, its deadline resets to the background default counted from the detach moment.

Wire this into shell mode so ! commands run with a 3-minute foreground timeout and get 10 minutes once detached to the background, instead of staying bounded by the original 60-second foreground deadline.

* feat(agent-core): lower shell mode foreground timeout to 2 minutes

docs/en/customization/themes.md

@@ -26,6 +26,7 @@ Custom themes can override the tokens below. The `dark` and `light` columns show
 | `diffGutter` | `#6B6B6B` | `#737373` | Diff line-number gutter |
 | `diffMeta` | `#888888` | `#5F5F5F` | Diff meta / hunk headers |
 | `roleUser` | `#FFCB6B` | `#9A4A00` | User message bullet and text, skill-activation name |
+| `shellMode` | `#BD93F9` | `#7C3AED` | Shell mode (`!`) prompt, editor border, and the echoed `$ command` line |
 
 ## Use the custom-theme skill
 

docs/en/guides/interaction.md

@@ -64,6 +64,16 @@ After producing a plan the agent pauses for your review — you can approve it,
 YOLO mode skips confirmation for file writes and command execution. Only use it in working directories you trust.
 :::
 
+### Shell mode
+
+Shell mode lets you run terminal commands without leaving the conversation. The command output is written into the conversation context, so the agent can see the results in later turns.
+
+- Enter: type `!` in an empty input box, or paste a command that starts with `!`.
+- Exit: press `Backspace` or `Esc` in an empty input box; submitting a command also returns you to normal mode automatically.
+- Run in background: while a command is running, press `Ctrl+B` to move it to a background task.
+
+In shell mode the input box shows a `!` prompt on the left and the border turns violet. For example, you can run `!gh auth login` to sign in to the GitHub CLI without opening a new terminal, so Kimi can use `gh` afterward.
+
 ## During streaming output
 
 The input box remains usable while the agent is thinking or calling tools, and supports the following extra actions:

docs/en/reference/keyboard.md

@@ -25,9 +25,12 @@ Pressing `Ctrl-C` **during streaming** cancels immediately — no second confirm
 | Shortcut | Function |
 | --- | --- |
 | `Shift-Tab` | Toggle Plan mode |
+| `!` | Enter shell mode (in an empty input box) |
 
 Press `Shift-Tab` to enable or disable Plan mode. When enabled, the Agent prioritizes read-only tools for research and planning and can write to the current plan file; `Bash` is subject to the current permission mode and regular rules, without any additional separate approval triggered by Plan mode. Simply toggling does not create an empty plan file. Press `Shift-Tab` again to exit Plan mode.
 
+Type `!` in an empty input box to enter shell mode and run terminal commands directly; while a command is running, press `Ctrl+B` to move it to a background task. See [Interaction and input](../guides/interaction.md#shell-mode).
+
 ## Input & Editing
 
 | Shortcut | Function |

docs/zh/customization/themes.md

@@ -26,6 +26,7 @@ Kimi Code CLI 可以使用内置配色，也可以使用自定义 JSON 主题文
 | `diffGutter` | `#6B6B6B` | `#737373` | diff 行号槽 |
 | `diffMeta` | `#888888` | `#5F5F5F` | diff 元信息 / hunk 头 |
 | `roleUser` | `#FFCB6B` | `#9A4A00` | 用户消息的子弹头与文字、技能激活名 |
+| `shellMode` | `#BD93F9` | `#7C3AED` | Shell 模式（`!`）的提示符、编辑器边框，以及回显的 `$ 命令` 行 |
 
 ## 使用 custom-theme skill
 

docs/zh/guides/interaction.md

@@ -64,6 +64,16 @@ Agent 输出方案后会等待你审批——可批准执行、拒绝、或要
 YOLO 模式会跳过文件写入和命令执行的确认，请只在受信任的工作目录下使用。
 :::
 
+### Shell 模式
+
+Shell 模式让你不离开对话就能运行终端命令，命令输出会写入对话上下文，AI 在后续轮次能够看到这些结果。
+
+- 进入：在空输入框中键入 `!`，或粘贴以 `!` 开头的命令。
+- 退出：在空输入框中按 `Backspace` 或 `Esc`；提交命令后也会自动回到普通模式。
+- 后台运行：命令执行期间按 `Ctrl+B` 可将其转为后台任务。
+
+进入 Shell 模式后，输入框左侧会显示 `!` 提示符，边框变为紫色。例如，无需新开终端就能运行 `!gh auth login` 登录 GitHub CLI，登录后 Kimi 就可以直接使用 `gh`。
+
 ## 流式输出期间
 
 Agent 思考或调用工具时，输入框仍然可用，支持以下额外操作：

docs/zh/reference/keyboard.md

@@ -25,9 +25,12 @@ Kimi Code CLI 的 TUI 交互模式支持一套键盘快捷键。键位按使用
 | 快捷键 | 功能 |
 | --- | --- |
 | `Shift-Tab` | 切换 Plan 模式 |
+| `!` | 在空输入框中进入 Shell 模式 |
 
 按 `Shift-Tab` 可开启或关闭 Plan 模式。开启后，Agent 会优先使用只读工具进行研究和规划，并可写入当前计划文件；`Bash` 按当前权限模式和普通规则处理，不会因 Plan 模式额外发起独立审批。单纯切换模式不会创建空计划文件。再次按 `Shift-Tab` 退出 Plan 模式。
 
+在空输入框中键入 `!` 进入 Shell 模式，可直接运行终端命令；命令运行期间按 `Ctrl+B` 可将其转为后台任务。详见[交互与输入](../guides/interaction.md#shell-模式)。
+
 ## 输入与编辑
 
 | 快捷键 | 功能 |