A local-first multi-agent app development platform, built on PenguinHarness
docs(skills): remote-claude-code relay, key-stepping, and switch rules (#317)
Yaowei Zhenga024fa3271a4
diff --git a/changelog/unreleased/2026-08-18-remote-claude-code-driving.md b/changelog/unreleased/2026-08-18-remote-claude-code-driving.mdnew file mode 100644index 00000000..283b7847--- /dev/null+++ b/changelog/unreleased/2026-08-18-remote-claude-code-driving.md@@ -0,0 +1,31 @@+# remote-claude-code skill v2: verbatim relay and capture-verified keystrokes++- **Date:** 2026-08-18+- **Type:** process+- **Scope:** `skills`, `docs`+- **PR:** [#317](https://github.com/Prism-Shadow/penguin-harness/pull/317)+- **Issue:** [#307](https://github.com/Prism-Shadow/penguin-harness/issues/307)++[中文版](2026-08-18-remote-claude-code-driving.zh.md)++The `remote-claude-code` library skill moved to v2, closing four gaps reported from real relayed sessions: the local agent answering in Claude Code's place, a "model + level" switch request read as one unknown model name, batched key sequences racing the TUI, and post-run suggestion text mistaken for the user's pending input. Troubleshooting rows, the verification checklist, the skill's frontmatter description and the bilingual `skills` docs tables were updated in sync, and a contract test was added over the new rules.++## Relay contract++- A new "Relaying a conversation" section made the relay literal: once a session is up, user messages reach Claude Code word-for-word, the local agent neither answers nor rephrases nor performs any part of the task itself, and it acts directly only on session control — switches, interrupt, attach and detach.+- Tool-permission prompts, clarifying questions and plan approvals became the user's call, carried out to the user and answered with the key they choose. The previous instruction to answer them through `send-keys` as they appeared was removed, and `--dangerously-skip-permissions` stayed the one standing approval.+- A message arriving mid-turn is held until the turn ends, or sent after a single `Escape` when the user wants the run stopped; a `capture-pane` failing with `can't find pane` or `no server running` was made a recognized dead session, rebuilt with `claude --continue`.+- Replies are read with scrollback (`capture-pane -p -S -200`) rather than a `tail` that returns a fragment, and the task/control boundary was drawn by subject: questions about the session are answered from a capture, everything about the work is forwarded unchanged.+- Input-line text surviving the end of a turn was documented as a Claude-generated suggestion that a capture cannot tell apart from real uncommitted input — never to be submitted, never to be reported as the user's unsent draft, and cleared by typing the new message.++## Verbatim transport++`send-keys -l` delivers an embedded newline as Return, splitting one user message into two Claude Code turns, and lets tmux's command parser swallow a `;` that ends the argument. Multi-line, long and punctuation-heavy messages were moved onto `load-buffer` plus `paste-buffer -d -p` from a quoted heredoc, and the delivery check was made exact — the input line must show the message and nothing else — with named recoveries for a merged line and for a paste that submitted itself.++## Keystroke stepping++Batched sequences such as `send-keys Up s` race the TUI and land keys on the previous selection. Every menu, picker and dialog was put under one key per `send-keys` call, a `capture-pane` between keys, and the expected state confirmed before the next key, bounded by an explicit failure branch: re-send a swallowed key once, correct a wrong move with the opposite key, and after two failed corrections stop and show the user the screen instead of improvising further keystrokes. The conversation examples in section 3 were split into text and Enter with a capture in between.++## Model and thinking level switches++"switch to fable5 max" was specified as two settings — the model and the thinking level — instead of one unknown model name, and is never forwarded as chat text. The rule was written for the shape of the request rather than that one example: it covers any language, including the Chinese phrasings the report was filed in, as well as level-only and model-only requests, with the level vocabulary spelled out and a closing capture required to show the requested value changed and the untouched one unchanged.diff --git a/changelog/unreleased/2026-08-18-remote-claude-code-driving.zh.md b/changelog/unreleased/2026-08-18-remote-claude-code-driving.zh.mdnew file mode 100644index 00000000..1be4ac30--- /dev/null+++ b/changelog/unreleased/2026-08-18-remote-claude-code-driving.zh.md@@ -0,0 +1,31 @@+# remote-claude-code skill v2:逐字转发与逐键截屏确认++- **Date:** 2026-08-18+- **Type:** process+- **Scope:** `skills`, `docs`+- **PR:** [#317](https://github.com/Prism-Shadow/penguin-harness/pull/317)+- **Issue:** [#307](https://github.com/Prism-Shadow/penguin-harness/issues/307)++[English](2026-08-18-remote-claude-code-driving.md)++`remote-claude-code` 库 Skill 升到 v2,修补了真实转发会话中反馈上来的四处缺口:本地 Agent 越俎代庖替 Claude Code 作答、把「模型 + 档位」的切换请求当成一个不认识的模型名、成批按键与 TUI 抢跑,以及把一轮结束后残留的建议文本误认成用户尚未发出的输入。故障排查表、验证清单、Skill 的 frontmatter 描述与中英两份 `skills` 文档表格同步更新,并为这批新规则补了一个契约测试。++## 转发契约++- 新增的「Relaying a conversation」一节把「转发」落到字面:会话建立之后,用户消息逐字送达 Claude Code,本地 Agent 既不作答、也不改写、更不代做任务的任何一部分,只对会话控制类请求——切换、打断、attach 与 detach——直接动手。+- 工具权限提示、澄清提问与计划确认改由用户拍板,原样带到用户面前,再按他选定的键作答;此前那条「出现时用 `send-keys` 顺手答掉」的指示被删除,`--dangerously-skip-permissions` 仍是唯一一项长期授权。+- 一轮进行中到达的消息会先扣住,等这轮结束再发;用户想立刻叫停时,改为按一次 `Escape` 后再发。`capture-pane` 报 `can't find pane` 或 `no server running` 被明确认定为会话已死,用 `claude --continue` 重建。+- 回复改用带回滚缓冲的 `capture-pane -p -S -200` 读取,不再用只能拿回片段的 `tail`;任务与控制的边界按主题划定:关于会话本身的问题就地看一眼截屏作答,关于工作内容的一律原样转发。+- 一轮结束后仍留在输入行里的文本,被写明是 Claude 生成的建议消息,截屏无法把它与用户真正未提交的输入区分开——不得提交,也不得当成用户的未发草稿回报;直接键入新消息即可让它消失。++## 逐字传输++`send-keys -l` 会把消息里嵌的换行当成 Return 送出,将一条用户消息劈成 Claude Code 的两轮;tmux 的命令解析器还会吞掉用来结束参数的 `;`。多行、长文以及标点密集的消息改走引号 heredoc 的 `load-buffer` 加 `paste-buffer -d -p`,「是否落到位」的检查也改成严格判定——输入行必须只显示这条消息、别无他物——并为「粘连成一行」和「粘贴时自行提交」两种情形各给了具名的补救办法。++## 逐键推进++`send-keys Up s` 这类成批按键会与 TUI 抢跑,按键落在上一次的选中项上。所有菜单、选择器与对话框一律改为:一次 `send-keys` 只发一个键,键与键之间插一次 `capture-pane`,确认到达预期状态再发下一个键;并配一条界限清楚的失败分支——被吞掉的键重发一次,走错的一步用反向键纠正,连续两次纠正仍不奏效就停手,把屏幕摆给用户看,而不是继续凭感觉敲下去。第 3 节的对话示例也拆成「文本」与「Enter」两步,中间隔一次截屏。++## 模型与思考档位切换++「switch to fable5 max」被明确为两项设置——模型与思考档位——而不是一个不认识的模型名,也一律不作为聊天内容转发。这条规则是按请求的形态写的,而非只认这一个例子:它覆盖任意语言,包括该问题原本使用的中文说法,也覆盖只切档位与只切模型的请求;档位词汇逐一列出,收尾还要求截屏确认——所请求的那一项确已改变,未被触及的那一项保持原样。diff --git a/packages/docs/content/skills.en.md b/packages/docs/content/skills.en.mdindex 55538f18..9997be4b 100644--- a/packages/docs/content/skills.en.md+++ b/packages/docs/content/skills.en.md@@ -65,7 +65,7 @@ The built-in Skills, by group (the group manifest is `SKILL_GROUPS` in `packages| | `humanizer` | Strip AI-writing tells from prose in any language and rewrite it into the register of books, newspapers and encyclopedias (not preinstalled: install from the library when needed) || Software Development | `web-design` | Penguin visual language for generated web pages and app UIs: design tokens, components, light/dark themes and chat layouts || | `software-engineering` | Complete software-engineering tasks: investigate and review code, implement fixes, features and refactors with minimal scope, validate changes, and report verified outcomes |-| | `remote-claude-code` | Run Claude Code on a remote host over SSH — a persistent expect session, headless `-p` with the stdin fix, a tmux-driven interactive TUI and multi-turn continuity (not preinstalled: install from the library when needed) |+| | `remote-claude-code` | Run Claude Code on a remote host over SSH — a persistent expect session, headless `-p` with the stdin fix, a tmux-driven interactive TUI (one capture-verified keystroke at a time, user messages relayed verbatim) and multi-turn continuity (not preinstalled: install from the library when needed) || AI App Development | `penguin-sdk` | Build AI and RAG apps on the SDK: the createSession/run streaming loop plus a complete retrieval recipe with chunk-revealing citations || | `penguin-cli` | Manage model API keys, default models and per-agent Vault secrets with the penguin CLI || | `agenthub-models` | Call model APIs through `@prismshadow/agenthub`: streaming text, image generation, speech synthesis and embeddings |diff --git a/packages/docs/content/skills.zh.md b/packages/docs/content/skills.zh.mdindex eb26ce36..21cc6e36 100644--- a/packages/docs/content/skills.zh.md+++ b/packages/docs/content/skills.zh.md@@ -65,7 +65,7 @@ Skill 库以 npm 包 `@prismshadow/penguin-skills` 发布,tarball 直接携带| | `humanizer` | 去除任意语言文本的 AI 味,把行文改写成书籍、报纸、百科式的风格(不预装,按需从技能库安装) || 软件开发 | `web-design` | 生成网页与应用界面的 Penguin 视觉语言:设计令牌、组件配方、明暗主题与聊天布局 || | `software-engineering` | 完成软件工程任务:调查与审查代码,以最小改动实现修复、特性与重构,验证改动并报告经过确认的结果 |-| | `remote-claude-code` | 通过 SSH 在远程主机上驱动 Claude Code:expect 持久会话、headless `-p` 的 stdin 修正、tmux 驱动的交互 TUI 与多轮续接(不预装,按需从技能库安装) |+| | `remote-claude-code` | 通过 SSH 在远程主机上驱动 Claude Code:expect 持久会话、headless `-p` 的 stdin 修正、tmux 驱动的交互 TUI(逐个按键并截屏确认,用户消息原样转发)与多轮续接(不预装,按需从技能库安装) || AI 应用开发 | `penguin-sdk` | 基于 SDK 构建 AI 与 RAG 应用:createSession/run 流式循环,外加带可溯源引用的完整检索配方 || | `penguin-cli` | 用 penguin CLI 管理模型 API Key、默认模型与各 Agent 的 Vault 密钥 || | `agenthub-models` | 经 `@prismshadow/agenthub` 调用模型 API:流式文本、图像生成、语音合成与 Embedding |diff --git a/packages/skills/skills/remote-claude-code/SKILL.md b/packages/skills/skills/remote-claude-code/SKILL.mdindex 3e1c8296..acde5c4f 100644--- a/packages/skills/skills/remote-claude-code/SKILL.md+++ b/packages/skills/skills/remote-claude-code/SKILL.md@@ -1,11 +1,11 @@---name: remote-claude-code-description: Run Claude Code on a remote host over SSH — a persistent expect-driven login session, headless claude -p with the stdin fix, the interactive TUI inside a remote tmux driven by send-keys/capture-pane, and multi-turn continuity via --session-id/--resume or stream-json; hosts and credentials are placeholders resolved at runtime from the user or the vault, never hardcoded.+description: Run Claude Code on a remote host over SSH — a persistent expect-driven login session, headless claude -p with the stdin fix, the interactive TUI inside a remote tmux driven by send-keys/capture-pane (one keystroke at a time, capture-verified; relayed user messages go through verbatim), and multi-turn continuity via --session-id/--resume or stream-json; hosts and credentials are placeholders resolved at runtime from the user or the vault, never hardcoded.short_description: Run Claude Code on remote hosts over SSH.short_description_zh: 在远程主机上通过 SSH 运行 Claude Code(持久会话 / headless / tmux 交互 / 多轮续接)。preinstall: false-version: 1-updated: 2026-08-10T00:00:00Z+version: 2+updated: 2026-08-18T00:00:00Z---# Remote Claude Code@@ -16,7 +16,7 @@ Drive Claude Code on a remote Linux host over SSH. Three modes, in increasing in2. **Headless (`claude -p`)** — one-shot or scripted calls, with the stdin fix that naive invocations need.3. **Interactive TUI** — the real Claude Code UI inside a remote `tmux` session, driven with `tmux send-keys` / `tmux capture-pane`. tmux is the way to do interactive use.-Reach for this skill when the user wants to run or drive Claude Code on a server, keep an SSH connection open across turns, or hold a continuous conversation with Claude Code on a remote box.+Reach for this skill when the user wants to run or drive Claude Code on a server, keep an SSH connection open across turns, or hold a continuous conversation with Claude Code on a remote box. In a relayed conversation you are a pure message pipe — the user's words go to Claude Code verbatim (section 4).## Before you start@@ -57,34 +57,111 @@ TERM=xterm-256color tmux new-session -d -s <sess> "claude"sleep 8tmux capture-pane -t <sess> -p | tail -25-# converse: send a message, wait for the turn, read the screen again-tmux send-keys -t <sess> "Introduce yourself in one sentence" Enter+# converse: type the message, confirm it landed, submit — text and Enter as separate calls (§3.3)+tmux send-keys -t <sess> -l "Introduce yourself in one sentence"+tmux capture-pane -t <sess> -p | tail -5 # exactly your message on the input line?+tmux send-keys -t <sess> Entersleep 20-tmux capture-pane -t <sess> -p | tail -30+tmux capture-pane -t <sess> -p -S -200 # scrollback: a long reply overflows the visible pane```-- Workspace trust dialog: it shows on the first launch in each project directory (`-p` mode skips it; `--dangerously-skip-permissions` does **not**). Answer it once via `tmux send-keys -t <sess> Enter`, or pre-accept it by setting `hasTrustDialogAccepted: true` for that project path in the remote `~/.claude.json` — back the file up first (`cp ~/.claude.json ~/.claude.json.bak-$(date +%s)`) and rewrite it with a JSON-aware tool (python), not sed.-- Tool-permission prompts: answer them through `send-keys` as they appear; launch with `--dangerously-skip-permissions` only when the user explicitly wants unattended runs on that host.+- Workspace trust dialog: it shows on the first launch in each project directory (`-p` mode skips it; `--dangerously-skip-permissions` does **not**). Answer it once via `tmux send-keys -t <sess> Enter` and capture to confirm it closed, or pre-accept it by setting `hasTrustDialogAccepted: true` for that project path in the remote `~/.claude.json` — back the file up first (`cp ~/.claude.json ~/.claude.json.bak-$(date +%s)`) and rewrite it with a JSON-aware tool (python), not sed.+- Tool-permission prompts, and any other question Claude Code puts to **the user** (clarifying questions, plan approvals): the decision is the user's, not yours. Report the prompt and its options, wait for the user's answer, then send that key (one key, capture-verified, §3.3). Never approve a tool call on the user's behalf — an approved command runs on their host. `--dangerously-skip-permissions` is the one standing approval you may act on, and only when the user explicitly asked for unattended runs on that host.- `TERM=xterm-256color` must be visible to the tmux **server** (prefix the `tmux new-session` call that starts it), or the TUI renders garbled and colorless.- Continuity is real: within one tmux session, follow-ups remember earlier turns ("what was my first question?" gets the right answer).- The user can join from their own terminal at any time: `ssh <ssh-user>@<remote-host>` → `su - <target-user>` → `tmux attach -t <sess>`.+- The session can die under you (host rebooted, `tmux kill-server`, someone closed it). A `capture-pane` that exits non-zero with `can't find pane: <sess>` or `no server running on ...` means exactly that — not a slow TUI, so don't retry keys into it. Confirm with `tmux has-session -t <sess>` (exit 0 alive, 1 gone), tell the user the session is gone, and rebuild it with `claude --continue` in the same working directory to pick the conversation back up. Never start a bare `claude` and keep relaying as if the earlier context were still there.### 3.1 Waiting out a long turn — don't hold SSH openA Claude Code turn can run for ten-plus minutes. Instead of keeping an SSH connection open to poll, place a **detached watcher** on the remote (`setsid nohup`, so it outlives the launching SSH session): it polls `tmux capture-pane` every 10s, and once the turn has been idle for 3 consecutive checks — the footer no longer shows `esc to interrupt` — it writes the final screen plus a `DONE` marker (or `TIMEOUT` past a cap). A blocking SSH loop then waits for the marker and returns the final screen, so the tool call effectively hangs until the turn is done. The full watcher script and the wait loop are in [`reference/completion-watcher.md`](reference/completion-watcher.md) — read it when you need this.-### 3.2 Input-line text may be a suggestion, not real input+### 3.2 Delivering a message — and why input-line text may be a suggestion++When an idle Claude Code TUI shows text on the input line (after `❯`) — above all right after a turn finishes — that is usually a **Claude-generated suggested next message**, not text the user typed and left pending, and a `capture-pane` dump cannot reliably tell the two apart. So never treat post-run input-line text as pending user input: don't submit it, don't report it to the user as their unsent draft, and don't try to clear or edit it. `tmux send-keys` only ever adds new text — it does not edit or "complete" that suggestion, and Enter submits what _you_ sent, not the suggestion. When the next message is due, just send it — new text makes the suggestion disappear on its own.-When an idle Claude Code TUI shows text on the input line (after `❯`), that is often a **Claude-generated suggested next message**, not text the user typed and left pending. `tmux send-keys` only ever adds new text — it does not edit or "complete" that suggestion, and Enter submits what _you_ sent, not the suggestion. So don't try to clear or edit the input line: just send your full instruction and submit it. Send arbitrary message text literally with `-l` (so punctuation and words like `Enter` aren't parsed as key names), then send Enter as its own keypress:+**A single plain line** goes through `send-keys -l` (literal mode, so punctuation and words like `Enter` aren't parsed as key names). Text and Enter are always separate calls, with a capture in between:```bashtmux send-keys -t <sess> -l "Your full message, punctuation and all"+tmux capture-pane -t <sess> -p | tail -5 # exactly your message on the input line?+tmux send-keys -t <sess> Enter+```++**Anything else — multi-line, pasted, long, or punctuation-heavy — goes through the paste buffer**, because `send-keys -l` corrupts exactly the messages a relay must not corrupt (both verified on tmux 3.3a):++- a newline inside the literal text is delivered as **Return**, so a two-line argument submits its first line on its own and leaves the second as a fresh draft — one user message becomes two Claude Code turns;+- a `;` that ends the argument is swallowed by tmux's own command-sequence parser: `-l "ends with semi;"` arrives as `ends with semi`. Characters vanish and nothing reports an error.++Load the text from a **quoted** heredoc (so neither the shell nor tmux re-parses `$`, backticks, quotes or backslashes) and paste it as one block. This uses the paste behavior §3 warns about on purpose: a bracketed paste lands in the input box as a **draft** and does not submit, so the separate `Enter` keypress stays the thing that sends it.++```bash+tmux load-buffer - <<'MSG'+The user's message, exactly as written —+newlines, "quotes", $signs and semicolons; all intact.+MSG+tmux paste-buffer -d -p -t <sess> # -p bracketed paste (stays a draft), -d drops the buffer after+tmux capture-pane -t <sess> -p | tail -8+tmux send-keys -t <sess> Enter+```++The landed check is **exact, not approximate**: the input line must show your message and nothing else. A large paste may collapse to a `[Pasted text #N +K lines]` placeholder instead of the text — that still counts as landed; check the line count, not the words. Two failures to watch for, both before you press Enter:++- **Merged** — your text sits next to something else on the line. Don't submit: clear the line (`tmux send-keys -t <sess> C-u`), send again, and if it still merges, tell the user rather than submitting a message they didn't write.+- **Already submitted** — the turn started on its own, without your Enter. That pane isn't honoring bracketed paste, so the message went in split across lines. Say so, and deliver the rest one `-l` line at a time rather than pasting again.++Once the input line is right, send Enter, then `capture-pane` again to confirm the turn started.++### 3.3 One keystroke at a time — capture between keys++The TUI processes keys asynchronously, so a batched sequence races it: `tmux send-keys -t <sess> Up s` delivers `s` before the menu has processed `Up`, and `s` acts on the **previous** selection. Two back-to-back `send-keys` calls with no check in between race the same way.++In every menu, picker, or dialog (`/model`, permission prompts, trust dialog), send **one key per `send-keys` call** and verify between keys: send → `capture-pane` → confirm the expected change (highlight moved, dialog opened or closed, value updated) → only then send the next key.++Know where you are going before you start: capture the picker once, read which row is highlighted now and which row you want, count the moves, and step that many times — never press `Up` and hope.++```bash+tmux send-keys -t <sess> Up+tmux capture-pane -t <sess> -p | tail -15 # highlight moved to the intended entry?tmux send-keys -t <sess> Enter+tmux capture-pane -t <sess> -p | tail -15 # menu closed, new value shown?```-Then `capture-pane` to confirm your text landed on the input line and the turn started.+If the capture doesn't show the change yet, wait a second and capture again — never fire the next key on faith. Re-capture up to three times (a few seconds in total), then act on what the screen actually shows instead of sending more keys blindly:++- **Nothing changed** — the key was swallowed: re-send that same key once, and verify again.+- **The wrong thing changed** — highlight moved the other way, a different dialog opened, a value flipped that you didn't touch: correct it with the opposite key (`Down` for a stray `Up`, `Escape` for a dialog you didn't want) and verify again. Never "fix" a wrong state by pressing on toward the goal.+- **Still not where you want it after two corrections** — stop. Show the user the captured screen and ask. A menu whose state you can't read is not something to improvise more keystrokes into: a wrong key in `/model` changes their model, and a wrong key in a permission prompt runs a command on their host.++Message text is the one exception to one-key-at-a-time: send the whole message in a single call (`-l` for one plain line, `load-buffer`/`paste-buffer` otherwise), confirm it sits on the input line, then Enter as its own keypress (§3.2).++### 3.4 Model and thinking level are two separate settings++A switch request that names a model **plus a level word** — "switch to fable5 max", "use opus high", "切换到 fable5 max" — means **two** settings: switch the **model** to the named one (Fable 5) **and** the **thinking level** to the named level (max). Never read the pair as one unknown model name, and never forward it as chat text for Claude Code to answer — it is session control you execute in the TUI (section 4).++The rule is about the shape of the request, not about those three examples. It fires on **any** message naming a model, a thinking level, or both, in any language — "换成 opus 高", "改成 max", "set thinking to high", "用 sonnet":++- **Level words** are `max`, `high`, `medium`/`med`, `low`, `none`/`off` and their Chinese equivalents (`最高`/`最大`, `高`, `中`/`中等`, `低`, `关`/`不思考`). A level word sitting next to a model name is always the thinking level — never part of the model's name.+- **Model + level** ("fable5 max") → set both, model first.+- **Level only** ("改成 max", "set thinking to high") → change the thinking level, leave the model alone.+- **Model only** ("switch to opus", "用 sonnet") → change the model, leave the level alone.+- Names arrive shortened, unspaced, or in the wrong case (`fable5` → Fable 5, `opus` → the Opus entry). Match them against the rows the picker actually shows; if nothing matches, say what the picker offers and ask — never pick the nearest-looking row.++Use Claude Code's own controls: type `/model` (`-l`, then Enter as its own key) and walk the picker one keystroke at a time per §3.3; when the build exposes the thinking level as its own entry or toggle rather than a per-model variant, set it in a second step the same way. Finish with a capture that shows **both** the new model and the new thinking level before telling the user the switch is done — for a level-only or model-only request, that the requested one changed **and** the other did not.++## 4. Relaying a conversation — the user's words go through verbatim++Once the session is up and the user is talking to Claude Code **through** you, you are a message pipe — nothing more:++- Forward every user message to Claude Code **verbatim**: the exact wording, unchanged — no answering it yourself, no rephrasing or translating, no summarizing, no doing any part of the task locally. Even when you know the answer or the task looks trivial: the user is talking to Claude Code, not to you.+- Deliver the message (§3.2), wait out the turn (§3.1), then report what Claude Code said — faithfully, without your own analysis, edits, or additions. Read the reply with scrollback (`capture-pane -p -S -200`), not `| tail -30`: a long answer runs off the visible pane and a tail hands the user a fragment presented as the whole reply.+- **Questions travel back, not to you.** When Claude Code asks something — a permission prompt, a clarifying question, a plan to approve — carry it to the user with its options and send the answer they give (§3.3). You never answer on their behalf; that is their conversation.+- **A message that arrives mid-turn waits.** If the footer still shows `esc to interrupt`, don't type into the running turn: hold the message, wait the turn out (§3.1), deliver it then, and tell the user it is queued behind the current run. If they clearly want to stop or redirect now ("stop", "停", "别做了"), send `Escape` as its own key, capture to confirm the working footer is gone, then deliver. Escape twice in a row is not a stronger interrupt — it opens Claude Code's rewind-to-an-earlier-message UI, so send one and check.+- The only requests you act on yourself are **session control**: model / thinking-level switches (§3.4), interrupting a stuck turn (Escape), attaching, detaching, or closing the session, and connection repair. Execute those against the TUI; everything else goes into the conversation verbatim.+- **Split by subject, not by phrasing.** Questions about the **session** — is it still running, what's on the screen, is the connection alive, did the turn finish — you answer yourself from a capture. Anything about the **work** goes through unchanged, including questions you could answer. A message that does both ("is it still going? when it's done have it add the tests too") goes to Claude Code in full, and you answer the session half locally.+- When in doubt whether a message is task or control, relay it verbatim — a mis-relayed control request is easy to recover; work silently done in Claude Code's place is not.-## 4. Continuous (multi-turn) conversation+## 5. Continuous (multi-turn) conversationThree verified ways to keep context across calls:@@ -107,7 +184,7 @@ Returns `system/init` (carrying the `session_id`), `assistant`, and `result` eve**c) The interactive tmux session (section 3)** — the true REPL-style continuous conversation.-## 5. Troubleshooting+## 6. Troubleshooting| Symptom | Cause / fix || ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |@@ -118,13 +195,23 @@ Returns `system/init` (carrying the `session_id`), `assistant`, and `result` eve| expect stuck producing no output | a prompt regex never matched → replace it with `sleep` + fixed sends || `Connection timed out during banner exchange` | busy server / transient → wait a few seconds and retry; keep one persistent session instead of hammering new ones || New SSH connections crawl while old ones work | connection pressure → route commands through the persistent session |-| Input line shows text you didn't type | it's a Claude Code suggestion, not real input (see §3.2) → don't edit it; `send-keys -l "<message>"` then `Enter` |+| Input line shows text you didn't type | a Claude Code suggestion, common right after a turn ends — not pending user input (see §3.2) → don't submit or edit it; `send-keys -l "<message>"` then `Enter` |+| Menu key acts on the wrong item (`Up` and `s` sent together) | keys batched faster than the TUI processes them → one key per `send-keys` call, `capture-pane` between keys (§3.3) |+| User asks for "fable5 max" / "opus high" / "改成 max" | model and/or thinking level — session control in the TUI (§3.4), not one unknown model, not a chat message to relay |+| Relayed message arrived split in two, or lost its last character | `send-keys -l` delivered an embedded newline as Return, or tmux ate a trailing `;` → deliver anything non-trivial with `load-buffer` + `paste-buffer -d -p` (§3.2) |+| `capture-pane` fails: `can't find pane` / `no server running` | the tmux session or server is gone → confirm with `tmux has-session -t <sess>`, tell the user, rebuild with `claude --continue`; never keep relaying into a fresh, context-less session (§3) |+| Menu key does nothing, or moves the wrong way | key swallowed or landed on the wrong row → re-send once / correct with the opposite key, verify; after two failed corrections stop and show the user the screen (§3.3) |+| User sends a new message while a turn is running | don't type into a live turn → hold it until the turn ends (§3.1), or `Escape` once (never twice) if they want to stop now (§4) || Want to wait out a long turn without holding SSH open | run a detached watcher on the remote (see §3.1) that polls `capture-pane` until idle and writes a `DONE`/`TIMEOUT` marker, then block on an SSH loop until it appears |-## 6. Verification checklist+## 7. Verification checklist- Persistent session: the probe returns `whoami`/`hostname`/`pwd`, and the prompt comes back after each command.- Headless: `claude -p "..." < /dev/null` prints the answer and exits.- Interactive: `capture-pane` shows your message on the input line, then the response, then the prompt again.+- Relay: what reached Claude Code's input line is word-for-word what the user sent — nothing merged in from a suggestion, no line split off, no character dropped — and the reply you report back is Claude Code's, read with scrollback so it isn't a truncated tail.+- Decisions: every permission prompt and question Claude Code raised was answered by the user, not by you.+- Menus: every keystroke was its own `send-keys` call, and a capture confirmed the expected state before the next key.+- Switches: after a model and/or thinking-level request, one final capture shows the requested value(s) changed and the untouched one unchanged.- Continuity: a follow-up that requires memory answers correctly (or the remote `~/.claude/projects/**/*.jsonl` shows the user entry).- Sanitization: no real host, user, or password appears in temp scripts left on disk or in your final answer — real values only ever come from the user or the vault at runtime.diff --git a/packages/skills/test/skills.test.ts b/packages/skills/test/skills.test.tsindex c49b3f51..6ec7a1ad 100644--- a/packages/skills/test/skills.test.ts+++ b/packages/skills/test/skills.test.ts@@ -430,6 +430,79 @@ describe("librarySkill", () => {expect(optimizationRaw).not.toMatch(/\n\s+max_score:/);});+ it("remote-claude-code relays verbatim, steps keys one at a time, and splits model+level switches", () => {+ // Issue #307: the four TUI-driving rules, version-bumped alongside the content change.+ const skill = librarySkill("remote-claude-code")!;+ expect(skill.version).toBeGreaterThanOrEqual(2);+ const content = skill.content.replace(/\s+/g, " ");++ // 1) Pure relay: user messages reach Claude Code word-for-word, no local work.+ expect(content).toContain(+ "## 4. Relaying a conversation — the user's words go through verbatim",+ );+ expect(content).toContain("you are a message pipe — nothing more");+ expect(content).toContain("Forward every user message to Claude Code **verbatim**");+ expect(content).toContain("the user is talking to Claude Code, not to you");+ expect(content).toContain(+ "When in doubt whether a message is task or control, relay it verbatim",+ );++ // 2) "switch to fable5 max" style requests set the model AND the thinking level.+ expect(content).toContain('"switch to fable5 max"');+ expect(content).toContain("means **two** settings");+ expect(content).toContain("Never read the pair as one unknown model name");+ expect(content).toContain("shows **both** the new model and the new thinking level");++ // 2b) The rule generalizes past its own examples: any language, level-only and model-only too.+ expect(content).toContain("any** message naming a model, a thinking level, or both");+ expect(content).toContain("**Level only**");+ expect(content).toContain("**Model only**");+ expect(content).toContain(+ "A level word sitting next to a model name is always the thinking level",+ );++ // 3) Key-sequence races: one key per send-keys call, capture-verified between keys.+ expect(content).toContain("acts on the **previous** selection");+ expect(content).toContain("one key per `send-keys` call");+ expect(content).toContain("never fire the next key on faith");+ // ... and a bounded failure branch when the capture shows the state was NOT reached.+ expect(content).toContain("**Nothing changed**");+ expect(content).toContain("**The wrong thing changed**");+ expect(content).toContain('Never "fix" a wrong state by pressing on toward the goal');+ expect(content).toContain("Show the user the captured screen and ask");++ // 4) Post-run composer text is an AI suggestion, not pending user input.+ expect(content).toContain("cannot reliably tell the two apart");+ expect(content).toContain("never treat post-run input-line text as pending user input");+ expect(content).toContain("new text makes the suggestion disappear on its own");++ // 5) Verbatim delivery survives the transport: `send-keys -l` splits newlines and eats a+ // trailing `;`, so anything non-trivial goes through load-buffer/paste-buffer.+ expect(content).toContain("goes through the paste buffer");+ expect(content).toContain("tmux load-buffer -");+ expect(content).toContain("tmux paste-buffer -d -p -t <sess>");+ expect(content).toContain("The landed check is **exact, not approximate**");+ expect(content).toContain("**Already submitted**");++ // 6) The decision on a permission prompt is the user's, never the relaying agent's.+ expect(content).toContain("Never approve a tool call on the user's behalf");+ expect(content).toContain("**Questions travel back, not to you.**");++ // 7) Mid-run messages, session/work boundary, dead session, untruncated reporting.+ expect(content).toContain("**A message that arrives mid-turn waits.**");+ expect(content).toContain("Escape twice in a row is not a stronger interrupt");+ expect(content).toContain("**Split by subject, not by phrasing.**");+ expect(content).toContain("tmux has-session -t <sess>");+ expect(content).toContain("claude --continue");+ expect(content).toContain("capture-pane -p -S -200");++ // The keystroke rule (§3.3) precedes the relay contract (§4) that leans on it.+ const stepIndex = skill.content.indexOf("### 3.3 One keystroke at a time");+ const relayIndex = skill.content.indexOf("## 4. Relaying a conversation");+ expect(stepIndex).toBeGreaterThan(-1);+ expect(relayIndex).toBeGreaterThan(stepIndex);+ });+it("rejects illegal-character names (path traversal guard) and never hits the filesystem", () => {for (const name of ["../penguin-sdk", "..", "penguin-sdk/SKILL.md", "a/../b", ".", ""]) {expect(librarySkill(name), name).toBeUndefined();