@idl3/claude-control 0.1.22 → 0.2.1

package/lib/sessions.js

@@ -16,6 +16,7 @@ import { promisify } from 'node:util';
 import { parseTuiStatus, prettyModel } from './tui.js';
 import { assignTranscripts, parseEtime } from './match.js';
 import { pinKey } from './pins.js';
+import { readPaneRegistry, gcPaneRegistry } from './pane-registry.js';
 
 const execFile = promisify(_execFile);
 
@@ -397,8 +398,21 @@ export class SessionRegistry extends EventEmitter {
       return true;
     });
 
-    // Only Claude panes have transcripts to match (shells don't).
-    const claudePanes = panes.filter((p) => isClaudeCmd(p.cmd));
+    // Classify every pane by its process subtree (a `claude` descendant) and get
+    // its claude start time in one ps snapshot. Falls back to the cmd heuristic
+    // only when ps is unavailable.
+    const paneProc = await this._buildPaneProc(panes);
+    const isClaudePane = (p) => {
+      const info = paneProc.get(p.target);
+      return info ? info.isClaude : isClaudeCmd(p.cmd);
+    };
+    const claudePanes = panes.filter(isClaudePane);
+
+    // The exact pane→transcript map authored by the SessionStart hook. This is
+    // the deterministic binding; everything below is fallback for panes with no
+    // hook record (sessions started before the hook was installed).
+    const paneReg = await readPaneRegistry();
+    gcPaneRegistry(new Set(panes.map((p) => p.paneId).filter(Boolean))).catch(() => {});
 
     // Manual pins win first: a pinned pane is force-bound to its transcript and
     // that transcript is removed from the auto-matcher pool. Pins are keyed by
@@ -415,29 +429,43 @@ export class SessionRegistry extends EventEmitter {
       }
     }
 
-    // Auto-match the rest with the deterministic 1:1 matcher (pinned panes and
-    // pinned transcripts excluded so nothing double-binds or gets stolen).
-    const autoPanes = claudePanes.filter((p) => !pinnedByTarget.has(p.target));
-    const [candidatesRaw, procStart] = await Promise.all([
-      this._buildCandidates(autoPanes),
-      this._buildProcStart(autoPanes),
-    ]);
+    // Hook-bound: a pane whose %N is in the registry binds to that EXACT
+    // transcript — no guessing. Pinned panes keep their pin.
+    const hookByTarget = new Map();
+    for (const p of claudePanes) {
+      if (pinnedByTarget.has(p.target)) continue;
+      const reg = p.paneId ? paneReg.get(p.paneId) : null;
+      if (!reg) continue;
+      const rec = await this._recordForPath(reg.transcriptPath);
+      if (rec) {
+        hookByTarget.set(p.target, rec);
+        pinnedPaths.add(rec.transcriptPath); // exclude from the auto-matcher pool
+      }
+    }
+
+    // Auto-match the rest with the deterministic timing matcher (pinned + hook
+    // panes and their transcripts excluded so nothing double-binds).
+    const autoPanes = claudePanes.filter(
+      (p) => !pinnedByTarget.has(p.target) && !hookByTarget.has(p.target),
+    );
+    const candidatesRaw = await this._buildCandidates(autoPanes);
     const candidates = candidatesRaw.filter((c) => !pinnedPaths.has(c.transcriptPath));
     const assignment = assignTranscripts(
       autoPanes.map((p) => ({
         target: p.target,
         windowName: p.windowName,
         cwd: p.cwd,
-        procStartMs: procStart.get(p.target) ?? null,
+        projectDir: encodeCwd(p.cwd), // scope candidates to this pane's own slug dir
+        procStartMs: paneProc.get(p.target)?.startMs ?? null,
       })),
       candidates,
     );
     for (const [target, rec] of pinnedByTarget) assignment.set(target, rec);
+    for (const [target, rec] of hookByTarget) assignment.set(target, rec);
 
     const sessions = panes.map((win) => {
-      const transcript = isClaudeCmd(win.cmd)
-        ? assignment.get(win.target) ?? null
-        : null;
+      const isClaude = isClaudePane(win);
+      const transcript = isClaude ? assignment.get(win.target) ?? null : null;
       const isPinned = pinnedByTarget.has(win.target);
       const id = win.target;
       // Pending = subscribed-tailer pending (live modal) OR transcript-derived
@@ -445,7 +473,7 @@ export class SessionRegistry extends EventEmitter {
       const pending =
         (this._pendingMap.get(id) ?? false) || !!transcript?.transcriptPending;
       const title = transcript?.customTitle || transcript?.aiTitle || null;
-      const ctx = this._ctxMap.get(win.target) || {};
+      const ctx = isClaude ? this._ctxMap.get(win.target) || {} : {};
 
       return {
         id,
@@ -455,6 +483,7 @@ export class SessionRegistry extends EventEmitter {
         title,
         tmuxName: win.windowName,
         target: win.target,
+        paneId: win.paneId, // stable tmux %N (survives renumber / grouped mirrors)
         sessionName: win.sessionName,
         windowIndex: win.windowIndex,
         paneIndex: win.paneIndex,
@@ -467,16 +496,19 @@ export class SessionRegistry extends EventEmitter {
         pending,
         pendingQuestion: transcript?.pendingQuestion ?? null,
         cmd: win.cmd,
-        isClaude: true,
+        isClaude,
+        kind: isClaude ? 'claude' : 'terminal',
+        ccShell: !!win.ccShell, // a composer >_ sister shell pane
+
         model: ctx.model || prettyModel(transcript?.model) || null,
         ctxPct: ctx.ctxPct ?? null,
-        thinking: this._thinkingMap.get(win.target) ?? false,
+        thinking: isClaude ? this._thinkingMap.get(win.target) ?? false : false,
       };
     });
 
-    // Only surface Claude sessions; skip plain shell panes. (assignTranscripts
-    // already guarantees 1:1, so no post-hoc collision dedup is needed.)
-    this._sessions = sessions.filter((s) => isClaudeCmd(s.cmd) || s.transcriptPath);
+    // Surface EVERY pane: Claude sessions AND plain terminals (each pane is a row;
+    // terminals render a live interactive terminal instead of a transcript).
+    this._sessions = sessions;
     this._maybeEmit();
     return this._sessions;
   }
@@ -630,7 +662,10 @@ export class SessionRegistry extends EventEmitter {
             extractTailRecord(r.filePath, r.mtime, r.birthtimeMs),
           ),
         );
-        for (const rec of recs) if (rec) candidates.push(rec);
+        // Tag each candidate with the project-dir slug it was found in, so the
+        // matcher scopes it to panes whose cwd produces the SAME slug (prevents a
+        // parent-dir pane stealing a child worktree's transcript).
+        for (const rec of recs) if (rec) candidates.push({ ...rec, projectDir: name });
       }),
     );
 
@@ -638,17 +673,22 @@ export class SessionRegistry extends EventEmitter {
   }
 
   /**
-   * Resolve each Claude pane's claude-process start time (ms epoch) for the
-   * start-time matching pass. One `ps` snapshot, then walk the process tree from
-   * each pane's shell pid to its `claude` descendant. Best-effort: panes whose
-   * proc can't be found map to null and fall through to other match passes.
+   * Classify each pane and resolve its claude-process start time in ONE `ps`
+   * snapshot. A pane is a Claude session iff its process subtree (from the pane
+   * shell pid) contains a `claude` descendant — far more reliable than the
+   * `pane_current_command` version-regex, which flips to `node`/`git` while
+   * Claude runs a tool. The same walk yields the claude start time (ms epoch)
+   * for the start-time matching fallback.
    *
-   * @param {import('./tmux.js').Window[]} claudePanes
-   * @returns {Promise<Map<string, number|null>>} target -> startMs
+   * Best-effort: if `ps` is unavailable every pane maps to {isClaude:false,
+   * startMs:null} and callers fall back to the cmd heuristic / other passes.
+   *
+   * @param {import('./tmux.js').Window[]} allPanes
+   * @returns {Promise<Map<string, {isClaude: boolean, startMs: number|null}>>} target -> info
    */
-  async _buildProcStart(claudePanes) {
+  async _buildPaneProc(allPanes) {
     const out = new Map();
-    if (claudePanes.length === 0) return out;
+    if (allPanes.length === 0) return out;
 
     let rows;
     try {
@@ -659,7 +699,7 @@ export class SessionRegistry extends EventEmitter {
       );
       rows = stdout.split('\n');
     } catch {
-      return out; // ps unavailable — every pane falls back to null
+      return out; // ps unavailable — callers fall back
     }
 
     /** @type {Map<number, number[]>} ppid -> child pids */
@@ -677,8 +717,8 @@ export class SessionRegistry extends EventEmitter {
     }
 
     const now = Date.now();
-    const findClaudeStart = (rootPid) => {
-      // BFS for a descendant whose command basename is `claude`.
+    // BFS from the pane shell pid for a `claude` descendant; return its start.
+    const findClaude = (rootPid) => {
       const queue = [rootPid];
       const seen = new Set();
       while (queue.length) {
@@ -688,15 +728,15 @@ export class SessionRegistry extends EventEmitter {
         const meta = info.get(pid);
         if (meta && CLAUDE_COMM_RE.test(meta.comm)) {
           const sec = parseEtime(meta.etime);
-          return sec == null ? null : now - sec * 1000;
+          return { isClaude: true, startMs: sec == null ? null : now - sec * 1000 };
         }
         for (const c of children.get(pid) ?? []) queue.push(c);
       }
-      return null;
+      return { isClaude: false, startMs: null };
     };
 
-    for (const p of claudePanes) {
-      out.set(p.target, p.panePid ? findClaudeStart(p.panePid) : null);
+    for (const p of allPanes) {
+      out.set(p.target, p.panePid ? findClaude(p.panePid) : { isClaude: false, startMs: null });
     }
     return out;
   }

package/lib/shell.js

@@ -0,0 +1,109 @@
+/**
+ * lib/shell.js — per-session "sister" shell panes for the composer's terminal
+ * mode (>_). Each Claude session gets its OWN scratch shell, created on demand
+ * as a pane in that session's window (so it shares the window and inherits the
+ * cwd), and reused thereafter. Marked with the pane option `@cc_shell` so it can
+ * be found again. It's a real PTY (tmux), so interactive flows (npm login,
+ * prompts, OTP) work.
+ *
+ * Security: same posture as the rest of the app — WS traffic is token-gated and
+ * bound to 127.0.0.1 / the tailnet; this is no broader than the existing ttyd
+ * escape hatch. Commands run as the server user.
+ */
+import * as tmux from './tmux.js';
+import { readConfig } from './config.js';
+
+/** "0:1.2" → "0:1" (drop the pane index to address the window). */
+function windowOf(target) {
+  return String(target || '').replace(/\.\d+$/, '');
+}
+
+// Control keys the UI may send (mirrors the `promptkey` allow-list philosophy —
+// the command body goes through send-keys -l as literal text; only these named
+// keys are interpreted). The set is generated but still a closed allow-list:
+// every value is a known tmux send-keys token, so no arbitrary key-name injection.
+// Covers the on-screen key bar (arrows / Tab / Esc / Ctrl-* / Home / End / paging)
+// so a phone keyboard can reach keys it can't physically produce.
+const ALPHA = 'abcdefghijklmnopqrstuvwxyz'.split('');
+const NAMED_KEYS = [
+  'Enter', 'Tab', 'BTab', 'Escape', 'BSpace', 'DC', 'IC', 'Space',
+  'Up', 'Down', 'Left', 'Right', 'Home', 'End', 'PPage', 'NPage',
+  'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12',
+];
+// Navigation keys with every Ctrl/Meta/Shift modifier combination, so a hardware
+// keyboard (e.g. iPad Magic Keyboard) can send Opt+Arrow word-jumps, Shift+Arrow
+// selection, etc. Prefix order is C-,M-,S- (matches the frontend navToken).
+const NAV_KEYS = ['Up', 'Down', 'Left', 'Right', 'Home', 'End', 'PPage', 'NPage'];
+const NAV_PREFIXES = ['', 'C-', 'M-', 'S-', 'C-M-', 'C-S-', 'M-S-', 'C-M-S-'];
+const NAV_COMBOS = NAV_KEYS.flatMap((k) => NAV_PREFIXES.map((p) => p + k));
+
+export const SHELL_KEYS = new Set([
+  ...NAMED_KEYS,
+  ...NAV_COMBOS, // Up/Down/.../NPage with C-/M-/S- combinations
+  ...ALPHA.map((c) => `C-${c}`), // C-a .. C-z
+  ...ALPHA.map((c) => `M-${c}`), // M-a .. M-z (Option/Meta)
+]);
+
+/**
+ * Ensure the sister shell pane for a session's WINDOW exists; return its target.
+ * Reuses the `@cc_shell`-marked pane in that window, or splits the window to make
+ * one (rooted at the session's cwd, `-d` so the Claude pane keeps focus). Falls
+ * back to creating a standalone window only if there's no window to split.
+ *
+ * @param {string} sessionTarget  e.g. "0:1.1" (the Claude pane)
+ * @param {string} [cwd]
+ * @returns {Promise<string>} sister shell pane target
+ */
+export async function ensureSessionShell(sessionTarget, cwd) {
+  const win = windowOf(sessionTarget);
+  const dir = typeof cwd === 'string' && cwd ? cwd : readConfig().defaultCwd;
+
+  // Reuse an existing marked sister pane in this window.
+  try {
+    const panes = await tmux.listPanes();
+    const sister = panes.find(
+      (p) => p.ccShell && windowOf(p.target) === win && tmux.isValidTarget(p.target),
+    );
+    if (sister) return sister.target;
+  } catch {
+    // fall through to create
+  }
+
+  // Split the session's window to add the sister shell (no focus steal).
+  let target;
+  if (win && tmux.isValidTarget(`${win}.0`)) {
+    target = await tmux.splitWindow({ windowTarget: win, cwd: dir });
+  } else {
+    // No resolvable window (e.g. session vanished) — create a standalone one.
+    target = await tmux.createWindow({ cwd: dir, name: 'cc-shell' });
+  }
+  if (!tmux.isValidTarget(target)) throw new Error('shell: invalid pane target');
+  await tmux.setPaneOption(target, '@cc_shell', '1');
+  return target;
+}
+
+/** Run a command line (literal text + Enter) in the session's sister shell. */
+export async function shellInput(sessionTarget, cwd, line) {
+  const target = await ensureSessionShell(sessionTarget, cwd);
+  await tmux.sendText(target, String(line ?? ''));
+}
+
+/** Forward literal keystroke text (NO Enter) for raw passthrough typing. */
+export async function shellText(sessionTarget, cwd, text) {
+  const target = await ensureSessionShell(sessionTarget, cwd);
+  await tmux.sendLiteral(target, String(text ?? ''));
+}
+
+/** Send one allow-listed control key (e.g. C-c). Throws on anything else. */
+export async function shellKey(sessionTarget, cwd, key) {
+  if (!SHELL_KEYS.has(key)) throw new Error('key not allowed');
+  const target = await ensureSessionShell(sessionTarget, cwd);
+  await tmux.sendRawKeys(target, [key]);
+}
+
+/** Capture the sister shell pane WITH ANSI escapes for the colored live view. */
+export async function shellCapture(sessionTarget, cwd, lines = 200) {
+  const target = await ensureSessionShell(sessionTarget, cwd);
+  const n = Math.max(1, Math.min(10000, Number(lines) || 200));
+  return tmux.capturePane(target, n, true);
+}

package/lib/tmux.js

@@ -177,6 +177,8 @@ const FORMAT = [
   '#{window_id}',
   '#{pane_index}',
   '#{pane_active}',
+  '#{pane_id}',
+  '#{@cc_shell}',
 ].join(SEP);
 
 /**
@@ -222,7 +224,7 @@ export async function listPanes() {
     const parts = trimmed.split(SEP);
     if (parts.length < 9) continue;
 
-    const [sessionName, rawIndex, windowName, rawActive, rawPid, cwd, cmd, windowId, rawPane, rawPaneActive] = parts;
+    const [sessionName, rawIndex, windowName, rawActive, rawPid, cwd, cmd, windowId, rawPane, rawPaneActive, paneId, ccShell] = parts;
     const windowIndex = Number(rawIndex);
     const panePid = Number(rawPid);
     const paneIndex = Number(rawPane) || 0;
@@ -239,6 +241,8 @@ export async function listPanes() {
       cmd,
       windowId: windowId ?? `${sessionName}:${windowIndex}`,
       paneIndex,
+      paneId: paneId ?? null, // stable tmux %N — joins to $TMUX_PANE from the hook
+      ccShell: ccShell === '1', // sister shell pane created for the composer >_
     });
   }
 
@@ -377,6 +381,54 @@ export async function createWindow({ cwd, name } = {}) {
   return target;
 }
 
+// ---------------------------------------------------------------------------
+// Split window (sister pane)
+// ---------------------------------------------------------------------------
+
+/**
+ * Split a window to add a sister pane running the default shell, WITHOUT
+ * stealing focus (`-d`), and return the new pane's target. Used to give each
+ * Claude session its own scratch shell next to it (composer >_).
+ *
+ * @param {{ windowTarget: string, cwd: string, size?: string }} opts
+ *   windowTarget e.g. "0:1"; size e.g. "30%" (height of the new pane).
+ * @returns {Promise<string>} new pane target "session:window.pane"
+ */
+export async function splitWindow({ windowTarget, cwd, size = '30%' } = {}) {
+  if (!windowTarget) throw new Error('splitWindow: windowTarget required');
+  if (typeof cwd !== 'string' || !cwd) throw new Error('splitWindow: cwd required');
+  const args = [
+    'split-window',
+    '-d', // do not switch focus to the new pane
+    '-v', // stack below the source pane
+    '-l', size,
+    '-t', windowTarget,
+    '-c', cwd,
+    '-P',
+    '-F', '#{session_name}:#{window_index}.#{pane_index}',
+  ];
+  const { stdout } = await runTmux(args);
+  const target = stdout.trim();
+  if (!isValidTarget(target)) {
+    throw new Error(`splitWindow: produced invalid target: ${JSON.stringify(target)}`);
+  }
+  return target;
+}
+
+/**
+ * Set a pane-scoped tmux option (e.g. a `@user` marker). Used to tag the sister
+ * shell pane so it can be found and reused later.
+ *
+ * @param {string} target  pane target
+ * @param {string} name    option name (e.g. "@cc_shell")
+ * @param {string} value
+ * @returns {Promise<void>}
+ */
+export async function setPaneOption(target, name, value) {
+  assertTarget(target);
+  await runTmux(['set-option', '-p', '-t', target, name, String(value)]);
+}
+
 // ---------------------------------------------------------------------------
 // Rename window
 // ---------------------------------------------------------------------------
@@ -416,6 +468,22 @@ export async function sendText(target, text) {
   await runTmux(['send-keys', '-t', target, 'Enter']);
 }
 
+/**
+ * Send literal text WITHOUT a trailing Enter — for raw keystroke passthrough,
+ * where each character (or a paste) is forwarded as the user types and the pane
+ * itself is the echo. `-l` means no key-name interpretation, so this can't inject
+ * control keys (those go through sendRawKeys with the SHELL_KEYS allow-list).
+ *
+ * @param {string} target
+ * @param {string} text
+ * @returns {Promise<void>}
+ */
+export async function sendLiteral(target, text) {
+  assertTarget(target);
+  if (!text) return;
+  await runTmux(['send-keys', '-t', target, '-l', text]);
+}
+
 // ---------------------------------------------------------------------------
 // Send raw key names (no -l)
 // ---------------------------------------------------------------------------
@@ -468,16 +536,14 @@ export async function sendRawKeysSequenced(target, keys, delayMs = 160) {
  * @param {number} [lines=40]  How many history lines above the visible area to include.
  * @returns {Promise<string>}
  */
-export async function capturePane(target, lines = 40) {
+export async function capturePane(target, lines = 40, escapes = false) {
   assertTarget(target);
-  const { stdout } = await runTmux([
-    'capture-pane',
-    '-t', target,
-    '-p',         // print to stdout
-    // NOTE: no '-e' — the UI renders the capture as plain text (LivePane <pre>,
-    // AskModal peek), so ANSI escapes would show as literal garbage. Strip them
-    // at the source by capturing without escape sequences.
-    '-S', `-${lines}`,  // start N lines above visible area
-  ]);
+  const args = ['capture-pane', '-t', target, '-p'];
+  // `-e` keeps ANSI/SGR sequences so the client can render terminal colors. Off
+  // by default: LivePane / AskModal render plain text (escapes would show as
+  // garbage). The composer terminal view opts in to get a themed, colored pane.
+  if (escapes) args.push('-e');
+  args.push('-S', `-${lines}`); // start N lines above the visible area
+  const { stdout } = await runTmux(args);
   return stdout;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idl3/claude-control",
-  "version": "0.1.22",
+  "version": "0.2.1",
   "type": "module",
   "description": "Local web UI to watch and drive your Claude Code sessions running in tmux — live transcripts, reply, answer AskUserQuestion, attach files, from a browser or phone.",
   "keywords": [
@@ -22,6 +22,8 @@
   "files": [
     "server.js",
     "lib/",
+    "hooks/",
+    "scripts/",
     "public/",
     "web/dist/",
     "bin/",
@@ -32,6 +34,8 @@
     "start": "node server.js",
     "dev": "node --watch server.js",
     "test": "node --test",
+    "eval:optimise": "node scripts/eval-optimize.mjs",
+    "install-hook": "node scripts/install-pane-hook.mjs",
     "build:web": "cd web && npm install && npm run build",
     "build": "npm run build:web",
     "prepack": "npm run build"

package/scripts/eval-optimize.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * eval-optimize.mjs — offline scorecard for the prompt-optimiser acceptance gate.
+ * Runs lib/optimize.js → evaluateRewrite over the deterministic fixture set and
+ * prints a per-case pass/fail table plus an aggregate. Exits non-zero on any
+ * mismatch so it can gate CI / catch regressions in the guard logic.
+ *
+ * Run: npm run eval:optimise
+ */
+import { evaluateRewrite } from '../lib/optimize.js';
+import { OPTIMIZE_CASES } from '../test/fixtures/optimize-cases.mjs';
+
+let pass = 0;
+const rows = [];
+for (const c of OPTIMIZE_CASES) {
+  const ev = evaluateRewrite(c.draft, c.optimized);
+  const verdictOk = ev.ok === c.expectOk;
+  // If the case pins expected violations, require they all fired.
+  const violOk =
+    !c.expectViolations || c.expectViolations.every((v) => ev.violations.includes(v));
+  const ok = verdictOk && violOk;
+  if (ok) pass += 1;
+  rows.push({
+    name: c.name,
+    ok,
+    got: ev.ok ? 'accept' : `reject(${ev.violations.join(',')})`,
+    want: c.expectOk ? 'accept' : `reject(${(c.expectViolations || []).join(',') || 'any'})`,
+    ratio: ev.metrics.lengthRatio,
+    overlap: ev.metrics.contentOverlap,
+  });
+}
+
+const W = Math.max(...rows.map((r) => r.name.length));
+console.log('Prompt-optimiser eval — acceptance gate\n');
+for (const r of rows) {
+  console.log(
+    `${r.ok ? '✓' : '✗'} ${r.name.padEnd(W)}  got=${r.got}  want=${r.want}  ` +
+      `ratio=${r.ratio} overlap=${r.overlap}`,
+  );
+}
+const total = OPTIMIZE_CASES.length;
+console.log(`\n${pass}/${total} cases passed`);
+if (pass !== total) {
+  console.error('EVAL FAILED — guard logic regressed');
+  process.exit(1);
+}

package/scripts/install-pane-hook.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * install-pane-hook.mjs — idempotently register the pane-recording hook
+ * (hooks/record-pane.mjs) as a Claude Code SessionStart + SessionEnd hook in
+ * ~/.claude/settings.json. Lets Claude Control bind each tmux pane to its EXACT
+ * transcript with zero guessing.
+ *
+ * Safe to re-run: detects an existing record-pane hook (by command substring)
+ * and leaves the file untouched if already installed. Preserves all other hooks.
+ */
+import { readFile, writeFile, mkdir, copyFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SETTINGS = path.join(homedir(), '.claude', 'settings.json');
+const SRC_SCRIPT = path.resolve(fileURLToPath(import.meta.url), '..', '..', 'hooks', 'record-pane.mjs');
+// Deploy to ~/.claude/scripts/ and reference it by $HOME — IDENTICAL to the
+// atlas-toolbox olam-skills hook (members/idl3/hooks/record-pane.json), so the
+// two install paths produce the same settings entry and never double-register.
+const DEST_SCRIPT = path.join(homedir(), '.claude', 'scripts', 'record-pane.mjs');
+const COMMAND = 'node "$HOME/.claude/scripts/record-pane.mjs"';
+const EVENTS = ['SessionStart', 'SessionEnd'];
+const MARKER = 'record-pane.mjs';
+
+async function readSettings() {
+  try {
+    return JSON.parse(await readFile(SETTINGS, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    throw new Error(`Could not parse ${SETTINGS}: ${err.message}`);
+  }
+}
+
+function alreadyInstalled(groups) {
+  return (groups || []).some((g) =>
+    (g.hooks || []).some((h) => typeof h.command === 'string' && h.command.includes(MARKER)),
+  );
+}
+
+async function main() {
+  // Deploy the script to ~/.claude/scripts/ (idempotent — always refresh it).
+  await mkdir(path.dirname(DEST_SCRIPT), { recursive: true });
+  await copyFile(SRC_SCRIPT, DEST_SCRIPT);
+
+  const settings = await readSettings();
+  settings.hooks ??= {};
+  let changed = false;
+
+  for (const event of EVENTS) {
+    const groups = (settings.hooks[event] ??= []);
+    if (alreadyInstalled(groups)) continue;
+    groups.push({ hooks: [{ type: 'command', command: COMMAND }] });
+    changed = true;
+  }
+
+  if (!changed) {
+    console.log(`✓ pane-recording hook already installed (${SETTINGS})`);
+    return;
+  }
+
+  await mkdir(path.dirname(SETTINGS), { recursive: true });
+  await writeFile(SETTINGS, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+  console.log(`✓ installed pane-recording hook → ${SETTINGS}`);
+  console.log(`  command: ${COMMAND}`);
+  console.log('  Applies to Claude sessions started from now on.');
+}
+
+main().catch((err) => {
+  console.error(`✗ ${err.message}`);
+  process.exit(1);
+});

package/server.js

@@ -14,6 +14,7 @@ import { WebSocketServer } from 'ws';
 
 import * as tmux from './lib/tmux.js';
 import * as terminal from './lib/terminal.js';
+import * as shell from './lib/shell.js';
 import { TranscriptTailer } from './lib/transcript.js';
 import { SubAgentsWatcher } from './lib/subagents.js';
 import { parsePanePrompt } from './lib/prompt.js';
@@ -1394,9 +1395,28 @@ async function handleClientMessage(ws, msg) {
       if (!session) throw new Error('unknown session');
       if (!tmux.isValidTarget(session.target)) throw new Error('invalid tmux target');
       const lines = Math.max(1, Math.min(10000, Number(msg.lines) || 40));
-      const text = await tmux.capturePane(session.target, lines);
+      // Terminal-pane rows opt into ANSI escapes so colours render; the plain
+      // LivePane omits the flag (escapes would show as garbage there).
+      const text = await tmux.capturePane(session.target, lines, !!msg.escapes);
       return send(ws, { type: 'capture', id: msg.id, text });
     }
+    // Interactive terminal panes: forward keystrokes to ANY pane by id (the
+    // selected one). Mirrors the cc-shell shell-* ops but target-addressed.
+    case 'pane-text': {
+      const session = sessionById(msg.id);
+      if (!session) throw new Error('unknown session');
+      if (!tmux.isValidTarget(session.target)) throw new Error('invalid tmux target');
+      await tmux.sendLiteral(session.target, String(msg.text ?? ''));
+      return send(ws, { type: 'ack', op: 'pane-text', ok: true });
+    }
+    case 'pane-key': {
+      const session = sessionById(msg.id);
+      if (!session) throw new Error('unknown session');
+      if (!tmux.isValidTarget(session.target)) throw new Error('invalid tmux target');
+      if (!shell.SHELL_KEYS.has(String(msg.key ?? ''))) throw new Error('key not allowed');
+      await tmux.sendRawKeys(session.target, [String(msg.key)]);
+      return send(ws, { type: 'ack', op: 'pane-key', ok: true });
+    }
     case 'promptkey': {
       // Respond to a live TUI selection prompt (permission/menu). Whitelisted
       // keys only — never arbitrary text — so this can't be used to inject input.
@@ -1411,6 +1431,33 @@ async function handleClientMessage(ws, msg) {
       if (sub) sub._lastPrompt = '__force__';
       return send(ws, { type: 'ack', op: 'promptkey', ok: true });
     }
+    // Composer terminal mode (>_): each Claude session has its OWN sister shell
+    // pane in its window. Resolve the session by id → its target + cwd, then act
+    // on (or lazily create) that window's sister shell.
+    case 'shell-input': {
+      const s = sessionById(msg.id);
+      if (!s) throw new Error('unknown session');
+      await shell.shellInput(s.target, s.cwd, String(msg.line ?? ''));
+      return send(ws, { type: 'ack', op: 'shell-input', ok: true });
+    }
+    case 'shell-text': {
+      const s = sessionById(msg.id);
+      if (!s) throw new Error('unknown session');
+      await shell.shellText(s.target, s.cwd, String(msg.text ?? ''));
+      return send(ws, { type: 'ack', op: 'shell-text', ok: true });
+    }
+    case 'shell-key': {
+      const s = sessionById(msg.id);
+      if (!s) throw new Error('unknown session');
+      await shell.shellKey(s.target, s.cwd, String(msg.key ?? ''));
+      return send(ws, { type: 'ack', op: 'shell-key', ok: true });
+    }
+    case 'shell-capture': {
+      const s = sessionById(msg.id);
+      if (!s) throw new Error('unknown session');
+      const text = await shell.shellCapture(s.target, s.cwd, msg.lines);
+      return send(ws, { type: 'shell-output', id: msg.id, text });
+    }
     default:
       return;
   }