@claudecollab/cli 0.1.2 → 0.2.0

package/packages/cli/bin/claude-share.js

@@ -28,6 +28,11 @@ import { execFile } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import ssh2 from 'ssh2';
 import { startPty } from '../src/pty.js';
+import { stripShimDir } from '../src/shim.js';
+import { shouldRunSetup, runSetup, setupMain } from '../src/setup-actions.js';
+import { startCtl } from '../src/ctl.js';
+import { ctlMain } from '../src/ctl-client.js';
+import { writeRoomFile, clearRoomFile } from '../src/room-file.js';
 import { paint, ROLE_GLYPH } from '../src/renderer.js';
 import { ScreenSnapshot } from '../src/screen-snapshot.js';
 import { installHooks, listenHooks } from '../src/hooks.js';
@@ -35,18 +40,26 @@ import { connectRelay, parseRelayUrl, openingMove } from '../src/relay-client.js
 import { createPinCheck } from '../src/known-relays.js';
 import { hostUrl, inviteUrl, readyToast } from '../src/invite.js';
 import { createPartitioner } from '../src/term-chatter.js';
-import { RoomState, HOST_ID, atLeast, FLOOR_COLS, FLOOR_ROWS } from '../src/brain/state.js';
+import { RoomState, HOST_ID, atLeast, FLOOR_COLS, FLOOR_ROWS, isScaledViewer } from '../src/brain/state.js';
 import { Queue } from '../src/brain/queue.js';
 import { Log } from '../src/brain/log.js';
 import { Drafts } from '../src/brain/drafts.js';
+import { History } from '../src/brain/history.js';
+import { extractLatestResponse } from '../src/brain/transcript.js';
 import { dispatch, classifySend, sendAllowed } from '../src/brain/gate.js';
 import { parse as parseCommand, permitted as commandPermitted, resolveMention } from '../src/brain/commands.js';
 import { build as buildCard, recapCard } from '../src/brain/card.js';
 import { foldKnock } from '../src/brain/knocks.js';
+import { askContext, summarizeToolInput } from '../src/brain/ask.js';
 
 function parseArgs(argv) {
   const opts = {
     relay: true,
+    // Lazy by default (spec phase 5a): a fresh `collab` starts pixel-identical to
+    // plain claude and does NOT dial the relay until go-live (`collab go`). --live
+    // restores the old behavior — dial at startup — for rigs, tests, and anyone who
+    // wants a room immediately. --no-relay still means never share.
+    live: false,
     // Default to the community relay so a fresh `collab` needs zero setup; dev
     // rigs and tests always pass --relay explicitly (ssh://127.0.0.1:2222).
     relayUrl: 'ssh://claudecollab.org:2222',
@@ -59,12 +72,16 @@ function parseArgs(argv) {
     secret: process.env.CLAUDE_SHARE_SECRET || undefined,
     fingerprint: undefined, // explicit relay key pin (SHA256:…); default is TOFU
     roomPassword: undefined, // optional join password guests must present before knocking
+    cap: undefined, // optional requested room size (--max-guests); the relay clamps it
+    yes: false, // --yes: skip the first-run setup screen (for scripts / non-interactive)
     childArgs: [],
   };
   const passthrough = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--no-relay') opts.relay = false;
+    else if (a === '--live') opts.live = true;
+    else if (a === '--yes') opts.yes = true;
     else if (a === '--relay') opts.relayUrl = argv[++i] ?? opts.relayUrl;
     else if (a === '--no-hooks') opts.hooks = false;
     else if (a === '--web-port') opts.webPort = Math.max(1, Number(argv[++i]) || opts.webPort);
@@ -73,7 +90,10 @@ function parseArgs(argv) {
     else if (a === '--secret') opts.secret = argv[++i] ?? opts.secret;
     else if (a === '--fingerprint') opts.fingerprint = argv[++i] ?? opts.fingerprint;
     else if (a === '--room-password') opts.roomPassword = argv[++i] ?? opts.roomPassword;
-    else if (a === '--') {
+    else if (a === '--max-guests') {
+      const n = Math.floor(Number(argv[++i]));
+      if (Number.isFinite(n) && n > 0) opts.cap = n; // a bad value is ignored (relay default stands)
+    } else if (a === '--') {
       passthrough.push(...argv.slice(i + 1));
       break;
     } else passthrough.push(a); // unknown flags pass through to the child
@@ -114,16 +134,53 @@ function loadHostKey() {
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
   const { stdin, stdout } = process;
+  // The room-creation secret is the WRAPPER's credential, captured into opts.secret
+  // above — scrub it from our environment NOW so no child ever inherits it (the pty
+  // child, hook processes, /recap's `claude -p`). Without this, the Claude inside a
+  // shared session could be prompted by any guest to echo $CLAUDE_SHARE_SECRET into
+  // the mirrored screen.
+  delete process.env.CLAUDE_SHARE_SECRET;
+
+  // ── first run: the one-screen setup (installs /collab + shims `claude`) ────────
+  // Shown ONCE, only on a real interactive run. The bold hazard: rigs/tests spawn
+  // interactive PTYs, so this MUST be gated off for them — every rig/e2e host spawn
+  // sets CLAUDE_SHARE_SKIP_SETUP=1 (shouldRunSetup honors it), or the suite hangs
+  // here at the picker. runSetup writes the shown-once marker when it completes.
+  if (shouldRunSetup({ stdinTTY: stdin.isTTY, stdoutTTY: stdout.isTTY, skipEnv: process.env.CLAUDE_SHARE_SKIP_SETUP, yes: opts.yes })) {
+    try {
+      await runSetup({ input: stdin, output: stdout });
+    } catch {
+      /* setup is best-effort — never block the session on it */
+    }
+  }
   // The terminal band is permanently exactly ONE status line, pinned to the bottom
   // row. Claude gets every other row; the child PTY is resized to rows-1 each repaint.
   const BAND_ROWS = 1;
   const multiplayer = opts.relay; // the guest composer/gate + mirror are active only when sharing
+  // Lazy sharing (spec phase 5a): pre-live, the wrapper is pixel-identical to plain
+  // claude — the relay is not dialed and the band paints ZERO rows, so the child owns
+  // every terminal row. wantLive flips exactly once, at go-live (--live at startup, or
+  // `collab go` over the control socket). isLive() gates every sharing-shaped behavior
+  // (band height, the shared-size clamp); bandRows() is the one height source.
+  let wantLive = opts.live;
+  const isLive = () => multiplayer && wantLive;
+  const bandRows = () => (isLive() ? BAND_ROWS : 0);
   // The host's browser tab authenticates with this token: it knocks with fingerprint
   // `webhost:<token>:<seat>`, and the brain auto-admits it as host. The token goes in
   // the room URL we print/copy; the SEAT does not — the browser mints it locally, so
   // possessing the (leak-prone) URL is not enough to take the host seat.
   const hostToken = randomBytes(16).toString('hex');
   const HOST_FP_PREFIX = `webhost:${hostToken}`;
+  // The room file the wrapped Claude reads to learn its own invite link. Its PATH is
+  // ALWAYS exported (CLAUDE_SHARE_ROOM_FILE, below) so "running under collab" is
+  // detectable; the file only EXISTS while a room is live (written on grant/reclaim,
+  // removed on gone/give-up/exit). Whitelisted: the host token never reaches it.
+  const roomFile = path.join(os.tmpdir(), `claude-share-room-${process.pid}.json`);
+  // The control socket the wrapped Claude drives with `collab go|off|status` (spec
+  // phase 5a). Its PATH is exported as CLAUDE_SHARE_CTL for every spawn; the socket
+  // itself is created below (0600, same-user only) and unlinked in cleanup(). The
+  // host URL/token NEVER crosses it — replies carry room + inviteUrl only.
+  const ctlPath = path.join(os.tmpdir(), `claude-share-ctl-${process.pid}.sock`);
   // The seat this session is bound to: the first host browser's seat secret claims
   // it; later browsers presenting the token with a different/absent seat are refused
   // (leaked-link defense). Reset by a host-terminal Ctrl-G handoff (see below).
@@ -163,6 +220,7 @@ async function main() {
   const queue = new Queue();
   const log = new Log();
   const drafts = new Drafts();
+  const history = new History(); // per-turn who-typed-what + Claude's response
   const toasted = new Set(); // userIds already shown the viewer toast
   const knockInfo = new Map(); // id -> {name, fp} captured at knock time
   const pointers = new Map(); // userId -> {x, y} normalized 0..1 (browser cursors)
@@ -177,6 +235,12 @@ async function main() {
   const admittedFps = new Set();
   const claude = { state: 'idle' };
   let armed = false; // true only while a permission ask is pending (hook-armed)
+  // What Claude is asking permission for (tool + a short, stripControls'd input
+  // summary), surfaced in the state snapshot while claude.state === 'ask' so the
+  // browser's ask card can show it. `lastTool` remembers the most recent tool this
+  // turn (its input is the best summary we get); both clear when the turn moves on.
+  let askInfo = null;
+  let lastTool = null;
   let pendingKnocks = []; // FIFO of guest {id,name,fp,seen} awaiting the host tab's admit
   let currentUrl = null; // the host-tab URL (WITH host token) — host's own terminal only
   let inviteUrlStr = null; // the token-free invite URL — safe to show guests in the mirror
@@ -185,6 +249,7 @@ async function main() {
   // text is dropped (drafts are created explicitly — never by stray typing).
   const nudgedAt = new Map();
   let relay = null;
+  let ctl = null; // the control-socket server (started below; closed in cleanup)
   let exited = false;
   // Reconnect-with-reclaim state (spec §failure-behavior: the relay holds the code
   // 10 min after a host drop). On a lost connection we reconnect and RECLAIM the
@@ -217,7 +282,16 @@ async function main() {
 
   let pty;
   try {
-    pty = await startPty({ cmd: opts.cmd, args: childArgs, bandRows: BAND_ROWS });
+    // CLAUDE_SHARE_ROOM_FILE is set for EVERY spawn, solo included: its presence
+    // tells the child it's running under collab; the file at that path appears only
+    // once a room is live (phase 5's skill relies on that live-vs-not distinction).
+    const childEnv = { CLAUDE_SHARE_ROOM_FILE: roomFile, CLAUDE_SHARE_CTL: ctlPath };
+    // Recursion guard: when the wrapped command is `claude`, strip the shim dir from
+    // the child's PATH so it resolves to the REAL claude, never back to the shim that
+    // execs us (stripShimDir is spike-proven; see src/shim.js). Any other --cmd keeps
+    // PATH untouched.
+    if (opts.cmd === 'claude') childEnv.PATH = stripShimDir(process.env.PATH, os.homedir());
+    pty = await startPty({ cmd: opts.cmd, args: childArgs, bandRows: bandRows(), env: childEnv });
   } catch (err) {
     process.stderr.write(
       `collab: could not start "${opts.cmd}": ${err.message}\n` +
@@ -272,9 +346,12 @@ async function main() {
   // the mirror letterboxed until the first guest join reshaped it.
   // Solo with no tab there is no shared view, so we use the host's own terminal.
   const viewSize = () => {
-    if (!multiplayer) return { cols: stdout.columns || 80, rows: stdout.rows || 24 };
+    // Pre-live (and solo) the child owns the real terminal exactly — no floor clamp,
+    // no resize theft. The shared-size clamp only governs once we are actually live.
+    if (!isLive()) return { cols: stdout.columns || 80, rows: stdout.rows || 24 };
     let { cols, rows } = state.clamp();
     for (const s of hostTabSizes.values()) {
+      if (isScaledViewer(s)) continue; // a below-floor host tab scales too — ignore its size
       cols = Math.min(cols, s.cols);
       rows = Math.min(rows, s.rows);
     }
@@ -310,7 +387,11 @@ async function main() {
     participants: state.list().map((p) => ({ id: p.id, name: p.name, role: p.role, color: p.color })),
     drafts: drafts.snapshot(),
     queue: queue.items.map((it, i) => ({ n: i + 1, author: it.author, text: it.text })),
+    history: history.snapshot(),
     claudeState: claude.state,
+    // What Claude is asking permission for, only while it is actually asking. The
+    // browser ask card reads this; approve/deny are ordinary keystrokes (role-gated).
+    ask: claude.state === 'ask' ? askInfo : null,
     paused: state.paused,
     pointers: Object.fromEntries(
       [...pointers]
@@ -366,7 +447,7 @@ async function main() {
   // Claude's region is resized to rows-1 so the line can never overlap its output.
   const repaintBand = () => {
     const { cols, rows } = viewSize();
-    const band = BAND_ROWS;
+    const band = bandRows(); // 0 pre-live (paint() no-ops, child keeps every row), 1 once live
 
     // Keep Claude's region to exactly the rows the band does not occupy, at the
     // shared width — resize the child only when that actually changes.
@@ -508,6 +589,32 @@ async function main() {
     t.unref?.();
   };
 
+  // Claude's response to the turn that just finished, read from the session
+  // transcript the Stop hook hands us (`transcript_path`). We read only the tail —
+  // the latest turn is at the end — so a long session's transcript stays cheap, and
+  // a truncated leading line is tolerated by the extractor. Any failure → '' (the
+  // window still shows the prompt; the response just stays blank).
+  const RESPONSE_TAIL_BYTES = 256 * 1024;
+  const captureResponse = (payload) => {
+    const file = payload && typeof payload.transcript_path === 'string' ? payload.transcript_path : null;
+    if (!file) return '';
+    try {
+      const fd = fs.openSync(file, 'r');
+      try {
+        const { size } = fs.fstatSync(fd);
+        const start = Math.max(0, size - RESPONSE_TAIL_BYTES);
+        const len = size - start;
+        const buf = Buffer.alloc(len);
+        fs.readSync(fd, buf, 0, len, start);
+        return extractLatestResponse(buf.toString('utf8'));
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch {
+      return '';
+    }
+  };
+
   const pump = () => {
     if (Date.now() < ptyLockUntil) {
       const retry = setTimeout(pump, 160);
@@ -529,6 +636,7 @@ async function main() {
     }, 120);
     enter.unref?.();
     claude.state = 'busy'; // optimistic; the UserPromptSubmit hook confirms
+    history.start(item.author, item.text); // open a turn; Stop closes it with the response
     armSubmitWatch();
     repaintBand();
   };
@@ -704,7 +812,7 @@ async function main() {
         runRecap(by);
         break;
       case 'end':
-        endSession();
+        endSession(parsed.save);
         break;
     }
     repaintBand();
@@ -727,13 +835,15 @@ async function main() {
 
   // /end — end the room now. The two-step "end? / save?" confirmation is a browser-UI
   // concern (the host tab gates it and fires a single /end); the terminal has no y/n
-  // path anymore. We write the attributed session.md then disconnect everyone —
-  // defaulting to save preserves the record, since the browser doesn't yet signal a
-  // no-save choice (spec §host controls: the log is kept in memory either way).
-  function endSession() {
-    try {
-      log.write(path.join(process.cwd(), 'session.md'));
-    } catch {}
+  // path anymore. The browser's "Save & end" sends `/end` (save) and "Just end" sends
+  // `/end nosave` (skip). `save` defaults to true so a bare host-typed /end still keeps
+  // the record; a nosave never touches disk (so it can't overwrite an existing file).
+  function endSession(save = true) {
+    if (save) {
+      try {
+        log.write(path.join(process.cwd(), 'session.md'));
+      } catch {}
+    }
     relay?.end();
     cleanup(0);
   }
@@ -956,6 +1066,8 @@ async function main() {
       if (!atLeast(role, 'host')) return;
       claude.state = 'idle';
       armed = false;
+      askInfo = null;
+      lastTool = null;
       log.event('host resynced claude state to idle');
       showToast('state resynced to idle');
       pump();
@@ -1007,13 +1119,23 @@ async function main() {
   // identically. Handlers use their own instance `r` for replies, so a stale
   // instance can never write to (or resurrect) a superseded connection.
   function wireRelay(r) {
+    // A superseded instance (off() tore it down mid-dial, or a reconnect replaced
+    // it) must never mutate room state: a stale late ROOM grant would resurrect a
+    // session the user just turned off, and a stale REFUSED would veto future gos.
+    // onClose below already carries the same guard.
+    const current = () => r === relay;
     r.onRoom((code, webUrl) => {
+      if (!current()) return;
       reconnectAttempts = 0;
       publicBase = webUrl || null; // a deployed relay's public https origin (or none)
       const reclaimed = state.room === code; // we already held this exact code → reclaim
       state.setRoom(code);
       currentUrl = hostRoomUrl(code); // the host's own tab URL lives in the status line
       inviteUrlStr = inviteRoomUrl(code); // the token-free variant the mirror shows guests
+      // Expose the live room's INVITE link to the wrapped Claude (whitelist drops the
+      // token-bearing host URL). Runs on create AND reclaim — a reclaim may carry a
+      // fresh publicBase, so the file is always rewritten from the current values.
+      writeRoomFile(roomFile, { room: code, inviteUrl: inviteUrlStr, webUrl: publicBase ?? undefined });
       if (reclaimed) {
         showToast('reconnected — room reclaimed', 6000);
         return;
@@ -1023,24 +1145,38 @@ async function main() {
       copyInvite(inviteRoomUrl(code), (copied) => showToast(readyToast(copied), 15000));
     });
     r.onGone(() => {
+      if (!current()) return;
       // Reclaim refused: the 10-min TTL lapsed, the relay restarted (fresh
       // registry), or the room truly ended. Nothing to return to — drop the code
       // AND its links (a dead URL on the band reads as a live room), finish solo.
       state.setRoom(null);
       currentUrl = null;
       inviteUrlStr = null;
+      clearRoomFile(roomFile); // the room is gone — the child must not read a dead link
       showToast('the room expired while disconnected — continuing solo', 8000);
       repaintBand();
     });
     r.onRefused((reason) => {
+      if (!current()) return;
       // The relay rejected our HELLO outright. 'secret' = it requires a room
-      // secret we didn't present (or ours is wrong). Terminal, not transient.
+      // secret we didn't present (or ours is wrong); 'version' = it speaks a newer
+      // protocol than we do (update the CLI). Terminal, not transient.
       relayVetoed = true;
-      const msg =
-        reason === 'secret'
-          ? 'relay requires a room secret — set CLAUDE_SHARE_SECRET (or --secret) and restart. running solo'
-          : `relay refused the connection (${reason}) — running solo`;
+      let msg;
+      if (reason === 'secret') msg = 'relay requires a room secret — set CLAUDE_SHARE_SECRET (or --secret) and restart. running solo';
+      else if (reason === 'version') msg = 'relay speaks a newer protocol — update with: npm update -g @claudecollab/cli. running solo';
+      else msg = `relay refused the connection (${reason}) — running solo`;
+      // A refusal means sharing never began — after the explanatory toast has had
+      // its 15s on the band, return the session to fully invisible (band gone, the
+      // child reclaims the row) instead of sticking a dead live-band on a solo
+      // session. goLiveStarted resets so a later `go` (fixed secret) can redial.
       showToast(msg, 15000);
+      const invis = setTimeout(() => {
+        wantLive = false;
+        goLiveStarted = false;
+        repaintBand();
+      }, 15000);
+      invis.unref?.();
       repaintBand();
     });
     r.onKnock((knock) => {
@@ -1159,7 +1295,9 @@ async function main() {
   // CLI was missing. Failures on a held room retry within the TTL; an initial
   // failure just runs solo.
   function openRelay() {
-    if (exited || relayVetoed) return;
+    // wantLive is the invariant: only a live-intending session may dial. Guards any
+    // stray timer/callback that survives an off() teardown (belt to off's braces).
+    if (exited || relayVetoed || !wantLive) return;
     // Fresh pin check per attempt (it re-reads the store, picking up a pin the
     // previous attempt just made). null = loopback dev relay, no verification.
     const pin =
@@ -1173,6 +1311,7 @@ async function main() {
         privateKey: loadHostKey(),
         secret: opts.secret,
         roomPass: opts.roomPassword,
+        cap: opts.cap,
         verifyHostKey: pin ? pin.verify : undefined,
       });
     } catch (err) {
@@ -1215,6 +1354,7 @@ async function main() {
     if (exited) return;
     if (!state.room) return showToast('relay disconnected — running solo', 8000);
     if (reconnectAttempts >= MAX_RECONNECT) {
+      clearRoomFile(roomFile); // gave up reclaiming — the room is no longer reachable
       return showToast('could not reconnect to the relay — continuing solo', 8000);
     }
     reconnectAttempts++;
@@ -1224,7 +1364,108 @@ async function main() {
     reconnectTimer.unref?.();
   }
 
-  if (opts.relay) openRelay();
+  // Go live on demand: dial the relay and flip wantLive so the band appears and the
+  // child shrinks by one row (via repaintBand's resize path). Idempotent — the guard
+  // makes it callable exactly once, whether from --live at startup or `collab go`
+  // mid-session over the control socket. --no-relay can never go live.
+  let goLiveStarted = false;
+  function goLive() {
+    if (goLiveStarted || exited || !opts.relay) return;
+    goLiveStarted = true;
+    wantLive = true;
+    openRelay();
+    repaintBand(); // band appears; the child is resized to rows-1
+  }
+  if (opts.relay && opts.live) goLive();
+
+  // ── control socket: `collab go|off|status` drives the room lifecycle ──────────
+  // The wrapped Claude connects here (CLAUDE_SHARE_CTL) to go live / stop / query
+  // WITHOUT restarting. Replies carry room + inviteUrl only — never the host URL or
+  // token (those stay on the host's own terminal / room file whitelist).
+  ctl = startCtl({
+    path: ctlPath,
+    handlers: {
+      // Go live: apply any valid overrides, dial the relay, and resolve on the FIRST
+      // of room-granted / relay-refused / 15s timeout. Idempotent when already live.
+      go: async (req) => {
+        if (!opts.relay) return { ok: false, error: 'sharing disabled (--no-relay)' };
+        if (state.room) return { ok: true, room: state.room, inviteUrl: inviteUrlStr ?? undefined };
+        // Overrides (each validated; a bad value is ignored so the current setting stands).
+        if (req.guests === 'viewer' || req.guests === 'prompter') opts.guests = req.guests;
+        if (Number.isFinite(req.max) && Math.floor(req.max) > 0) opts.cap = Math.floor(req.max);
+        if (typeof req.pass === 'string' && req.pass.length) opts.roomPassword = req.pass;
+        goLive();
+        if (!relay) return { ok: false, error: 'sharing unavailable' };
+        // One-shot waiter over the live relay instance — do not restructure wireRelay,
+        // just resolve on whichever event lands first. wireRelay's own onRoom runs
+        // before this one (subscribed earlier), so inviteUrlStr is set by the time
+        // we read it. onClose covers a dead/vetoed relay so `go` can't hang 15s.
+        return await new Promise((resolve) => {
+          let done = false;
+          let offRoom, offRefused, offClose, timer;
+          const finish = (v) => {
+            if (done) return;
+            done = true;
+            offRoom?.();
+            offRefused?.();
+            offClose?.();
+            clearTimeout(timer);
+            resolve(v);
+          };
+          offRoom = relay.onRoom((code) => finish({ ok: true, room: code, inviteUrl: inviteUrlStr ?? inviteRoomUrl(code) }));
+          offRefused = relay.onRefused((reason) => finish({ ok: false, error: `relay refused (${reason})` }));
+          offClose = relay.onClose(() => finish({ ok: false, error: relayVetoed ? 'relay refused the connection' : 'relay unavailable' }));
+          timer = setTimeout(() => finish({ ok: false, error: 'relay timeout' }), 15000);
+          timer.unref?.();
+        });
+      },
+      // Stop sharing: end the room, tear down the relay, clear the links + room file,
+      // drop the band (repaint), and let a later `go` dial again. Idempotent.
+      off: async () => {
+        if (state.room || relay) {
+          const r = relay;
+          relay = null; // null first so the instance's onClose sees r !== relay (no reconnect)
+          try {
+            r?.end();
+          } catch {}
+          try {
+            r?.close();
+          } catch {}
+          // Disarm any pending reclaim: a reconnect timer left ticking would dial
+          // openRelay() after this teardown and HELLO a brand-new room with the band
+          // hidden — an invisibly-live room, the one thing off() must make impossible.
+          clearTimeout(reconnectTimer);
+          reconnectTimer = null;
+          reconnectAttempts = 0;
+          state.setRoom(null);
+          currentUrl = null;
+          inviteUrlStr = null;
+          clearRoomFile(roomFile);
+          wantLive = false;
+          goLiveStarted = false;
+          // Purge every participant footprint — the process now OUTLIVES the room, so
+          // stale guests would haunt the next go (wrong count, crushed size clamp,
+          // orphaned drafts/queue items). forgetGuest also logs each departure.
+          for (const g of [...state.guests()]) forgetGuest(g.id);
+          pendingKnocks = [];
+          knockInfo.clear();
+          pointers.clear();
+          hostTabIds.clear();
+          hostTabSizes.clear();
+          guestPartitioners.clear();
+          repaintBand(); // band disappears; the child reclaims the row
+        }
+        return { ok: true };
+      },
+      // Query without changing anything. inviteUrl only — never the host URL/token.
+      status: async () => ({
+        ok: true,
+        live: !!state.room,
+        room: state.room ?? undefined,
+        inviteUrl: inviteUrlStr ?? undefined,
+      }),
+    },
+  });
 
   // ── hook events → brain ───────────────────────────────────────────────────────
   if (hooks) {
@@ -1233,21 +1474,30 @@ async function main() {
       clearSubmitWatch(); // the submission is confirmed — the optimistic busy is real
       claude.state = 'busy';
       armed = false;
+      askInfo = null; // a new turn is running — forget the previous turn's ask/tool
+      lastTool = null;
       repaintBand();
     });
-    hooks.on('idle', () => {
+    hooks.on('idle', (payload) => {
       lastHookAt = Date.now();
       clearSubmitWatch();
       claude.state = 'idle';
       armed = false;
+      askInfo = null; // the turn closed — the ask (if any) is answered
+      lastTool = null;
+      // Close the open turn with Claude's response, read cleanly from the session
+      // transcript the Stop hook points us at (never scraped from the TUI).
+      if (history.open) history.finish(captureResponse(payload));
       pump();
       repaintBand();
     });
-    hooks.on('ask', () => {
+    hooks.on('ask', (payload) => {
       lastHookAt = Date.now();
       clearSubmitWatch();
       claude.state = 'ask';
       armed = true; // the ONLY thing that arms a composing-side y/n → Claude (spec: gate on events)
+      // Capture WHAT Claude is asking (tool + short summary) for the browser ask card.
+      askInfo = askContext(payload, lastTool);
       repaintBand();
     });
     hooks.on('tool', (p) => {
@@ -1258,11 +1508,13 @@ async function main() {
       // a real turn flips busy here instead; its Stop still returns to idle.
       if (claude.state === 'idle') claude.state = 'busy';
       const name = p?.tool_name ?? 'tool';
-      const files = [];
       const inp = p?.tool_input ?? {};
+      const files = [];
       for (const key of ['file_path', 'path', 'notebook_path']) {
         if (typeof inp[key] === 'string') files.push(inp[key]);
       }
+      // Remember this tool as the context for an ask that may follow this turn.
+      lastTool = { name, summary: summarizeToolInput(inp) };
       log.tool(name, files);
       repaintBand();
     });
@@ -1298,6 +1550,9 @@ async function main() {
     try {
       hooks?.close();
     } catch {}
+    try {
+      ctl?.close(); // close the control socket and unlink its file
+    } catch {}
     for (const f of [settingsFile, socketPath]) {
       if (f) {
         try {
@@ -1305,6 +1560,7 @@ async function main() {
         } catch {}
       }
     }
+    clearRoomFile(roomFile); // the session is over — the link is dead (covers /end, exit, signals)
     stdout.write(TERM_RESTORE + '\r\n[claude-share exited]\r\n');
     process.exit(code ?? 0);
   };
@@ -1385,7 +1641,25 @@ async function main() {
   repaintBand(); // draw the band immediately, before the first frame
 }
 
-main().catch((err) => {
+// `collab relay [args]` IS the relay (single-bin: npx resolves one bin). serve.js
+// runs on import and reads process.argv — splice ours out so its args line up.
+let run;
+const sub = process.argv[2];
+if (sub === 'relay') {
+  process.argv.splice(2, 1);
+  run = import('../../relay/bin/serve.js');
+} else if (sub === 'go' || sub === 'off' || sub === 'status') {
+  // Run INSIDE a wrapped session: drive it via the control socket (CLAUDE_SHARE_CTL)
+  // and print a human-readable result. ctlMain owns its own exit code.
+  run = ctlMain(sub, process.argv.slice(3));
+} else if (sub === 'setup') {
+  // Re-run the first-run screen + actions ignoring the marker; `--undo` reverses the
+  // shim + plugin. setupMain owns its own exit code.
+  run = setupMain(process.argv.slice(3));
+} else {
+  run = main();
+}
+run.catch((err) => {
   process.stderr.write(`collab: ${err?.stack || err}\n`);
   process.exit(1);
 });

package/packages/cli/src/brain/ask.js

@@ -0,0 +1,67 @@
+// What Claude is asking permission for — the context the browser's ask card shows.
+//
+// The permission gate arms on a `Notification` hook (notification_type ===
+// 'permission_prompt'); that payload carries only a human `message` string (real
+// Claude: "Claude needs your permission to use Bash"), never the tool's structured
+// input. The concrete input (a command, a file path) is only known if a `tool`
+// (PostToolUse) hook fired earlier in the SAME turn — the fake-claude fixture fires
+// one, real Claude may not (there is no PreToolUse hook injected). So we take the
+// best available: the last tool's name + input summary when we have it, otherwise
+// the Notification message.
+//
+// Whatever we surface leaks no more than the host's own log already shows: it is
+// stripControls'd and clamped, so a crafted tool input can never smuggle escape
+// sequences or a wall of text into every guest's screen.
+
+import { stripControls } from './log.js';
+
+/** Max length of the ask summary shown on the card (spec: a short input summary). */
+export const ASK_SUMMARY_MAX = 120;
+const TOOL_MAX = 40;
+
+// Input fields worth showing, most-useful first. A tool's summary is the first of
+// these that is a non-empty string (a command, an edited file, a search pattern…).
+const SUMMARY_FIELDS = ['command', 'file_path', 'path', 'notebook_path', 'pattern', 'prompt', 'url', 'description'];
+
+/**
+ * Pull a short, safe summary string out of a tool's input object.
+ * @param {object} [toolInput]
+ * @returns {string}
+ */
+export function summarizeToolInput(toolInput) {
+  const inp = toolInput && typeof toolInput === 'object' ? toolInput : {};
+  for (const key of SUMMARY_FIELDS) {
+    if (typeof inp[key] === 'string' && inp[key].trim() !== '') return inp[key];
+  }
+  return '';
+}
+
+// Collapse whitespace runs (newlines/tabs survive stripControls) to single spaces so
+// the summary is one clean line, then strip controls and clamp.
+function clean(s, max) {
+  return stripControls(String(s ?? ''))
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+// Best-effort tool name out of a permission message: "…use Bash", "allow Edit?".
+function toolFromMessage(msg) {
+  const m = /\b(?:use|allow|run|permission (?:to use|for))\s+([A-Za-z][A-Za-z0-9_]*)/i.exec(String(msg ?? ''));
+  return m ? m[1] : '';
+}
+
+/**
+ * Build the ask context for the state snapshot from the arming Notification payload
+ * and the last tool seen this turn (either may be absent).
+ * @param {object} [payload]  the 'ask' (Notification) hook payload
+ * @param {{name?:string, summary?:string}|null} [lastTool]  last PostToolUse this turn
+ * @returns {{tool:string, summary:string}}
+ */
+export function askContext(payload, lastTool) {
+  const msg = payload && typeof payload.message === 'string' ? payload.message : '';
+  const tool = (lastTool && lastTool.name) || toolFromMessage(msg) || 'tool';
+  // Prefer the concrete tool input we saw; else the Notification's human message.
+  const rawSummary = (lastTool && lastTool.summary) || msg || '';
+  return { tool: clean(tool, TOOL_MAX), summary: clean(rawSummary, ASK_SUMMARY_MAX) };
+}