Feature request: external wake channel for running interactive sessions

Feature request: external wake channel for running interactive sessions

Use case

I run Kimi Code CLI as an interactive TUI and use a local "agent mail" system: other agents on the same or other (connected via SSH) machines drop Markdown messages into an inbox directory. An inotifywait-based watcher detects new mail the instant it lands, but it has no way to tell the running Kimi session to read and act on it. The agent only notices mail when the user manually says "check mail" or at session start.

Current behavior

• Detection works: inotifywait sees the new file immediately.
• Wake is missing: there is no documented API/hook/socket for an external process to inject a prompt or otherwise wake a running interactive TUI session.
• The only native "wake" we found is the scheduled-task/cron system, but its fire injects visible output into the chat, which is too disturbing for this workflow (and is unrelated to the actual mail event).

Desired behavior

An external process should be able to tell an idle/running Kimi CLI session: "something happened, please process it." The agent would then take a turn and decide what to do (e.g. read mail, act on it, reply).

Suggested implementations (any of these would solve it)

1. New hook event SessionWake / ExternalEvent in [[hooks]], triggered by an external command such as:

   kimi wake --session <id> --event mail --payload '{"from":"kimi-k3"}'
   

   The hook script receives the payload on stdin and can return text that is appended to context, optionally requesting a new turn.

2. Unix socket / HTTP control endpoint per running session (e.g. $KIMI_CODE_HOME/sessions/<id>/control.sock) that accepts a JSON message and injects it as a synthetic user message.

3. Filesystem-watch hook in [[hooks]]:

   [[hooks]]
   event = "FileChanged"
   matcher = "~/agent-mail/local/inbox-kimi-k27/.*\\.md"
   command = "~/agent-mail/bin/mail-hook.sh"
   

Why existing mechanisms don't work

• Hooks: the documented events (UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, SubagentStart, SubagentStop, Interrupt, PreCompact, PostCompact, Notification, PermissionRequest/Result) are all internal lifecycle events. None fire on external filesystem/mail events.
• Skills / Agents / Plugins: prompt/slash-command driven; no external trigger.
• ACP: IDE JSON-RPC protocol, not a generic external event channel.
• Background tasks: in kimi -p with print_background_mode = "steer", a background task completion can steer a new turn. In the interactive TUI this does not happen.
• TTY injection / signals: sending keystrokes or SIGWINCH forces a redraw and triggers the existing TUI jump-to-start bug (#2474).

Environment

• Kimi Code CLI version: 0.31.1
• OS: Linux (Ubuntu 24.04)
• Terminal: various (issue is independent of terminal emulator)

Related issues

• #2474 — TUI jumps to the top of the session after redraws; any wake mechanism should avoid triggering this.

Acceptance criteria

• An external process can cause a running/idle Kimi CLI session to take a turn within a few seconds.
• The wake mechanism does not produce disturbing chat output or TUI redraws.
• The injected event/prompt is visible to the agent so it can act on it (e.g. read new mail).

Start by reviewing the existing hooks, scheduled-task/cron behavior, interactive TUI, and background-task steering described in the issue, along with related issue #2474. Define and implement one external wake path that lets a running session take a turn, exposes the event to the agent, avoids disturbing chat output or redraws, and satisfies all listed acceptance criteria.