@penguinharness/use-claude-code 0.2.9

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="3" y="8" width="14" height="12" rx="2" />
+  <path d="M6.3 12.2l2.7 2.3-2.7 2.3" />
+  <path d="M11 17.2h3.2" />
+  <path d="M17.5 5.2a3 3 0 0 1 3 3" />
+  <path d="M17.5 2.7a5.5 5.5 0 0 1 5.5 5.5" />
+</svg>

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@penguinharness/use-claude-code",
+  "version": "0.2.9",
+  "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.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Prism-Shadow/penguin-harness.git",
+    "directory": "plugins/use-claude-code"
+  },
+  "files": [
+    "plugin.json",
+    "icon.svg",
+    "skills",
+    "hooks",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.json

@@ -0,0 +1,8 @@
+{
+  "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 交互 / 多轮续接）。",
+  "version": "2026-08-18.1",
+  "category": "software-development",
+  "preinstall": false
+}

package/skills/remote-claude-code/SKILL.md

@@ -0,0 +1,212 @@
+---
+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 (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.
+---
+
+# Remote Claude Code
+
+Drive Claude Code on a remote Linux host over SSH. Three modes, in increasing interactivity:
+
+1. **Persistent SSH session** — one long-lived expect-driven connection you keep feeding commands across turns.
+2. **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. In a relayed conversation you are a pure message pipe — the user's words go to Claude Code verbatim (section 4).
+
+## Before you start
+
+If the user's message only invokes this skill without a concrete task, ask what they want — at minimum the remote host, the SSH user, and what Claude Code should do there.
+
+Credential rules — non-negotiable:
+
+- This document contains **no real credentials**: `<ssh-user>`, `<remote-host>`, `<target-user>`, `<sess>` are placeholders you substitute at runtime from what the user provides or from this agent's **key vault** (suggested keys: `REMOTE_SSH_HOST`, `REMOTE_SSH_USER`, `REMOTE_SSH_PASSWORD`). Vault values reach your shell environment on the next task — check with `[ -n "$REMOTE_SSH_PASSWORD" ] && echo ok || echo missing`, and if missing ask the user to add the keys to the key vault (gear icon on the agent card → settings → key vault tab) or to provide the values in chat.
+- **Never hardcode a password** into scripts left on disk, deliverables, or your final answer. Have expect read it from the environment (`$env(...)`); if the user pasted it in chat, export it only into the running process's environment, scrub it from logs and replies, and delete any temp file that embeds it as soon as the session is done.
+- Prefer SSH keys when they are already set up — then no password tooling is needed at all.
+- Back up remote config before modifying it, and never copy remote credential stores (`~/.claude/.credentials.json`, OAuth fields of `~/.claude.json`, private keys) anywhere.
+
+## 1. Persistent SSH session (expect)
+
+One long-lived connection with password auto-login and an optional user switch, held open by `interact`. `expect` ships with macOS and is a one-command install on Linux; `sshpass` is usually absent, so expect is the password-interactive tool of choice.
+
+The full expect template plus its operating notes live in [`reference/persistent-session.md`](reference/persistent-session.md) — read that file when setting up this mode. In short: write the template to your scratchpad, fill the placeholders at runtime (the password comes from `$env(REMOTE_SSH_PASSWORD)`, never hardcoded), start it with `exec_command`, and drive the held-open connection through its `process_id` with `input_command`. Reuse this one session for most remote commands rather than opening a new connection each time.
+
+## 2. Headless Claude Code (`claude -p`) — the stdin gotcha
+
+`claude -p "<prompt>"` hangs forever when its stdin is an open pipe that never closes — which is exactly what agent harnesses and the expect session above provide. The process idles with no output and no network connections. Fix: redirect stdin from `/dev/null`:
+
+```bash
+claude -p "Reply with exactly: all good" < /dev/null
+```
+
+Same for `--resume`, `--session-id`, `--output-format stream-json`, and the rest. Exception: when input is _meant_ to come from stdin (`--input-format stream-json`), feed it through a pipe that closes (`echo '<json>' | claude ...`) and do **not** add `< /dev/null` — that would override the pipe.
+
+Symptom checklist: process running + no output + no TCP connections → stdin starvation; add `< /dev/null`.
+
+## 3. Interactive TUI — tmux is the way
+
+Launching `claude` interactively inside the expect/pipe session renders the welcome screen, but pipe input is treated as a **paste**: text lands in the input box and Enter (`\r`) is inserted literally, so the message is never submitted (the remote transcript `~/.claude/projects/<dir>/*.jsonl` gains no user entry). Run Claude Code inside a remote `tmux` session instead and drive it with `tmux send-keys`, which delivers discrete keypresses:
+
+```bash
+# start detached, then read the screen
+TERM=xterm-256color tmux new-session -d -s <sess> "claude"
+sleep 8
+tmux capture-pane -t <sess> -p | tail -25
+
+# 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> Enter
+sleep 20
+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` 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 open
+
+A 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 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.
+
+**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:
+
+```bash
+tmux 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?
+```
+
+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.
+
+## 5. Continuous (multi-turn) conversation
+
+Three verified ways to keep context across calls:
+
+**a) Same session across headless invocations (simplest):**
+
+```bash
+SID=$(uuidgen)
+claude -p "Remember: my name is Alex." --session-id "$SID" < /dev/null
+claude -p "What is my name?" --resume "$SID" < /dev/null   # answers: Alex
+```
+
+**b) stream-json real-time protocol (programmatic):**
+
+```bash
+echo '{"type":"user","message":{"role":"user","content":"Hello"}}' \
+  | claude -p --verbose --input-format stream-json --output-format stream-json
+```
+
+Returns `system/init` (carrying the `session_id`), `assistant`, and `result` events; reuse the `session_id` to continue. `--output-format stream-json` requires `--verbose`.
+
+**c) The interactive tmux session (section 3)** — the true REPL-style continuous conversation.
+
+## 6. Troubleshooting
+
+| Symptom                                                     | Cause / fix                                                                                          |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `claude -p` runs forever, no output, no TCP connections     | stdin pipe never closes → add `< /dev/null`                                                          |
+| TUI renders once then ignores keys; Enter shows up literally | pipe input treated as a paste → drive it with tmux `send-keys`                                       |
+| Trust dialog on every launch                                | `hasTrustDialogAccepted` unset for that project dir → set it to true (back up `~/.claude.json` first) |
+| TUI garbled / no colors                                     | `TERM=dumb` → set `xterm-256color` at expect spawn or tmux launch                                    |
+| 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                       | 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 |
+
+## 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.

package/skills/remote-claude-code/reference/completion-watcher.md

@@ -0,0 +1,69 @@
+# Waiting out a long turn — remote completion watcher
+
+A single Claude Code turn can run for ten-plus minutes. Rather than hold an SSH connection open
+polling `tmux capture-pane`, place a **detached watcher** on the remote (`setsid nohup`, so it
+outlives the SSH session that launched it). It polls the pane every 10s and, once the turn has been
+idle for 3 consecutive checks — the footer no longer shows the working indicator `esc to interrupt`
+(rendered as e.g. `✳ Cultivating… (esc to interrupt)` while a turn runs) — writes the final screen
+to a file with a `DONE` marker; past a hard cap it writes `TIMEOUT` instead. A blocking SSH loop
+then waits for the marker and returns the final screen, so the tool call "hangs until done".
+
+Replace `<sess>` with your tmux session name. `esc to interrupt` is the stable part of the working
+footer; the gerunds (`Cultivating`, `Improvising`, …) are flavor text that varies by version, so
+key detection on `esc to interrupt` and treat the rest as backup.
+
+## 1. Install and start the watcher (detached)
+
+```bash
+ssh <ssh-user>@<remote-host> 'cat > ~/cc-watch.sh <<'"'"'EOF'"'"'
+#!/usr/bin/env bash
+LOG=~/cc-watch.log; OUT=~/cc-final.txt
+rm -f "$LOG" "$OUT"
+busy_seen=0; idle_count=0; max_wait=7200; start=$(date +%s)
+echo "WATCHER START $(date)" >> "$LOG"
+while :; do
+  now=$(date +%s)
+  if (( now - start > max_wait )); then
+    tmux capture-pane -t <sess> -p > "$OUT"; echo "TIMEOUT $(date)" >> "$LOG"; exit 0
+  fi
+  live=$(tmux capture-pane -t <sess> -p 2>/dev/null | tail -30)
+  if printf "%s\n" "$live" | grep -qE "esc to interrupt|Cultivating|Improvising|Running "; then
+    busy_seen=1; idle_count=0
+  elif [ "$busy_seen" = 1 ]; then
+    idle_count=$((idle_count+1))
+    if [ "$idle_count" -ge 3 ]; then
+      tmux capture-pane -t <sess> -p > "$OUT"; echo "DONE $(date) after $(( now - start ))s" >> "$LOG"; exit 0
+    fi
+  fi
+  sleep 10
+done
+EOF
+chmod +x ~/cc-watch.sh
+setsid nohup bash ~/cc-watch.sh >/dev/null 2>&1 < /dev/null &
+sleep 2; ps aux | grep -v grep | grep cc-watch.sh'
+```
+
+## 2. Block until the marker appears, then return the final screen
+
+```bash
+ssh <ssh-user>@<remote-host> '
+for i in $(seq 1 900); do
+  if grep -qE "DONE|TIMEOUT" ~/cc-watch.log 2>/dev/null; then
+    echo "=== WATCHER LOG ==="; cat ~/cc-watch.log
+    echo; echo "=== FINAL CAPTURE ==="; cat ~/cc-final.txt 2>/dev/null
+    exit 0
+  fi
+  sleep 10
+done'
+```
+
+If the blocking loop times out before the marker appears, run it again (or, on a persistent
+session, poll again with `input_command`) — the watcher keeps running on the remote regardless.
+
+## Notes
+
+- `tail -30` inspects only the live bottom region of the pane, so an old `Cultivating` line scrolled
+  up into history can't be misread as "still busy".
+- Requiring 3 consecutive idle checks avoids a false "done" during a brief pause between tool calls
+  within one turn.
+- The user can read the result themselves at any time: `cat ~/cc-final.txt`.

package/skills/remote-claude-code/reference/persistent-session.md

@@ -0,0 +1,46 @@
+# Persistent SSH session — expect template
+
+Full template for mode 1 (persistent SSH session). Write it to your scratchpad
+(`<app_data_dir>/agents/<agent_id>/scratchpad/remote_shell.exp`) and fill the placeholders at
+runtime — never commit real values, and have expect read the password from the environment rather
+than baking it into the file.
+
+```expect
+#!/usr/bin/expect -f
+set timeout 30
+log_user 0
+set env(TERM) xterm-256color          ;# must be set before spawn — see the TERM note below
+spawn ssh -o StrictHostKeyChecking=accept-new -o ServerAliveInterval=30 \
+    -o ServerAliveCountMax=3 -o ConnectTimeout=15 <ssh-user>@<remote-host>
+expect {
+    "yes/no"    { send "yes\r"; exp_continue }
+    "password:" { send "$env(REMOTE_SSH_PASSWORD)\r"; exp_continue }
+    eof         { puts "\n=== SSH CLOSED ==="; exit 1 }
+}
+sleep 2
+send "su - <target-user>\r"           ;# drop this block when no user switch is needed
+expect {
+    "Password:" { send "$env(REMOTE_SSH_PASSWORD)\r"; exp_continue }
+    timeout { }
+}
+sleep 1
+send "echo PERSISTENT_SESSION_READY; whoami; hostname; pwd\r"
+expect "PERSISTENT_SESSION_READY"
+log_user 1
+set timeout -1
+interact
+```
+
+## Operating notes
+
+- Start it with `exec_command` and let it keep running — the closing `interact` holds the
+  connection open, and its `process_id` is your handle: send remote commands with `input_command`
+  (write to stdin) and poll the same session for new output.
+- The `sleep`-based waits replace prompt-regex matching on purpose: matching shell prompts
+  (`[$#] $` and friends) breaks on MOTD/ANSI noise and leaves the script stuck in `expect`.
+- `set env(TERM) xterm-256color` before `spawn`, or the remote shell sees `TERM=dumb` and TUIs
+  render badly.
+- Probe before relying on the session (`echo PING; whoami`), and reuse it for most remote commands
+  — open extra one-shot connections sparingly.
+- When finished: stop the expect process you started (and its ssh child; leave other people's
+  sessions alone) and delete the script from the scratchpad.