@prohost/cli 0.13.3 → 0.15.0

package/dist/codehost/tmux.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Pure tmux helpers for the Mac terminal host — the same shape as the cloud
+ * sandbox's terminal server (`shared/sandbox/template_coding/terminal-server/lib.js`),
+ * ported here rather than imported: the CLI ships on npm on its own.
+ *
+ * Same names as the sandbox — session `prohost`, viewers attached as grouped
+ * sessions so each keeps its own current window — with two differences a
+ * shared machine needs:
+ *
+ * - **Its own tmux server** (`tmux -L prohost-<home digest>`). The operator's own tmux, its
+ *   sessions and its config are never touched, and nothing here can be
+ *   attached to by accident from their terminal.
+ * - **A window per thread**, not one `agent` window per sandbox: `a-<terminal>`
+ *   runs the agent, `s-<terminal>` is a shell in the same worktree, made the
+ *   first time someone asks for it.
+ *
+ * tmux owns the processes, so a thread outlives the daemon: a restarted daemon
+ * finds its windows again with {@link listWindowsArgs} and the `@prohost_*`
+ * window options set at creation.
+ */
+import type { ViewerClient } from './sizing.js';
+/** Prefix of `tmux -L <socket>`: this host's private tmux server (one per `$PROHOST_HOME`). */
+export declare const TMUX_SOCKET_PREFIX = "prohost";
+export declare const TMUX_SESSION = "prohost";
+/** The window the session is created with, so it exists while no thread runs. */
+export declare const HOME_WINDOW = "home";
+export type TerminalWindow = 'agent' | 'shell';
+export declare const TERMINAL_WINDOWS: ReadonlySet<string>;
+/** Terminal and thread ids: what tmux names, env values and URL paths can all carry as-is. */
+export declare const ID_PATTERN: RegExp;
+export declare const DEFAULT_COLS = 120;
+export declare const DEFAULT_ROWS = 32;
+export declare const MAX_DIM = 1000;
+/**
+ * The private server's config, written beside the settings and passed with
+ * `-f`. Mirrors `shared/sandbox/template_coding/tmux.conf`, except for sizing
+ * (each window is made `window-size manual` and sized by the host, see
+ * `sizing.ts`), the hidden window-edge border and copy-mode position box, and
+ * `scroll-on-clear off` (Mac-only for now: the sandbox config is rebuilt with
+ * its template).
+ */
+export declare const TMUX_CONF = "# Written by `prohost agent run` for this machine's Code-thread terminals.\n# A private tmux server (tmux -L prohost-\u2026); your own tmux is not affected.\nset -g status off\n# Esc must reach Claude Code immediately (it interrupts a turn).\nset -s escape-time 10\nset -g default-terminal \"tmux-256color\"\nset -g history-limit 50000\n# Claude Code clears the whole screen and redraws it on every width change; with this on\n# (tmux's default) each old screen was kept in scrollback, so its header showed up once per\n# resize. A redraw longer than the screen still scrolls into history, so the host also keeps\n# width changes few (`sizing.ts`). -q: tmux before 3.3 has no such option.\nset -gq scroll-on-clear off\nset -g mouse on\n# Three lines per wheel step, as in a native terminal; tmux's five makes a\n# trackpad jump. Both copy-mode tables: mode-keys follows $EDITOR.\nbind -T copy-mode WheelUpPane select-pane \\; send-keys -X -N 3 scroll-up\nbind -T copy-mode WheelDownPane select-pane \\; send-keys -X -N 3 scroll-down\nbind -T copy-mode-vi WheelUpPane select-pane \\; send-keys -X -N 3 scroll-up\nbind -T copy-mode-vi WheelDownPane select-pane \\; send-keys -X -N 3 scroll-down\n# A program in the pane may not set anyone's clipboard through tmux: OSC 52\n# from the pane is ignored. Pinned rather than left to the default, which was\n# `on` before tmux 2.6. tmux still offers its own copies to the attached\n# terminal as OSC 52; whether a viewer writes them to the system clipboard is\n# that viewer's choice (the web terminal's gated clipboard addon, #21271).\n# The default drag binding is kept on purpose: it leaves copy mode on mouse-up,\n# so the next keystroke (a person's, or a relayed reply's) reaches the agent.\nset -s set-clipboard external\n# Windows are sized by the host, never by whichever viewer was active last: it\n# picks one viewer per window (the first to show it, then whoever types, focuses\n# or asks) and resizes the window to it (`sizing.ts`); `resize-window` makes\n# that window `window-size manual`. A new window is resized at once to the\n# size it will be viewed at. Not manual globally: tmux 3.4's server exits at\n# start with that in its config.\nset -g window-size latest\n# A viewer bigger than the window (someone smaller sizes it) sees blank space\n# beyond it, not tmux's dotted fill. -q: tmux before 3.3 has no such option.\nset -gq fill-character \" \"\n# ...and no border at the window's edge: tmux draws one there in the active\n# border's green. Spaces in the terminal's own colours instead.\nset -g pane-border-style default\nset -g pane-active-border-style default\nset -gq pane-border-lines spaces\nsetw -g aggressive-resize on\n# Scrolling back (copy mode) shows no \"[4/120]\" position box over the agent's\n# screen. -q: an older tmux has no such option (and shows the box).\nset -gq copy-mode-position-format \"\"\n# Window names are an API (the host targets them by name) \u2014 nothing may rename them.\nsetw -g automatic-rename off\nsetw -g allow-rename off\nset -g set-titles off\nset -g focus-events on\n";
+export declare function isValidId(value: unknown): value is string;
+/** tmux window name for one of a thread's windows. */
+export declare function windowName(terminalId: string, window: TerminalWindow): string;
+/** `prohost:<window>` — an exact target, never a prefix match. */
+export declare function windowTarget(name: string): string;
+/**
+ * The private server's socket name for one `$PROHOST_HOME`. Two agent homes on
+ * one machine (the desktop app's and a terminal's) must not manage one
+ * server's windows: each hook would read the other's token.
+ */
+export declare function socketNameFor(home: string): string;
+/** Arguments every invocation starts with. */
+export declare function baseArgs(socket: string, confPath: string): string[];
+export declare function hasSessionArgs(): string[];
+export declare function newSessionArgs(cwd: string): string[];
+export interface NewWindowSpec {
+    name: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** A shell command line; tmux runs it with `sh -c`. */
+    command: string;
+}
+export declare function newWindowArgs(spec: NewWindowSpec): string[];
+/** Window options that let a restarted daemon re-adopt a thread. */
+export interface WindowMeta {
+    terminalId: string;
+    codeThreadId: string;
+    agent: string;
+    cwd: string;
+    /**
+     * Started by a build that tracks Claude Code's trust with the ready mark (`ready.ts`): such a
+     * window is past its dialog only once a hook wrote the mark, never by adoption.
+     */
+    readyMark?: boolean;
+}
+export declare function setWindowMetaArgs(name: string, meta: WindowMeta): string[][];
+export declare function listWindowsArgs(): string[];
+export interface ListedWindow {
+    name: string;
+    meta?: WindowMeta;
+    /** The window's first pane's process (the agent's command), when tmux says. */
+    panePid?: number;
+}
+/** Parse {@link listWindowsArgs} output; windows without valid metadata keep only their name. */
+export declare function parseListWindows(stdout: string): ListedWindow[];
+/** A fresh, unguessable name for one viewer's grouped session. */
+export declare function viewSessionName(): string;
+/**
+ * argv (after {@link baseArgs}) that attaches one viewer to window `name`.
+ *
+ * A grouped session (`new-session -t prohost`), as in the sandbox: it shares
+ * every window but keeps its own current window, so one viewer on a shell
+ * never moves another off the agent. `destroy-unattached` reaps it when the
+ * viewer goes. `-u`: the viewer is xterm.js, which is always UTF-8 (see
+ * {@link utf8Env}).
+ */
+export declare function attachArgs(name: string, viewName: string): string[];
+/** What tmux and its panes run under when the daemon's own env has no UTF-8 locale. */
+export declare const UTF8_CTYPE = "C.UTF-8";
+/**
+ * `env` with a UTF-8 character locale, for every tmux this host runs.
+ *
+ * A daemon started by launchd (or any GUI parent) usually has no LANG at all,
+ * and a tmux client without a UTF-8 locale draws every non-ASCII cell as `_` —
+ * Claude Code's ⏺ bullets, its logo, an em dash. The server that client starts
+ * passes the same locale to the agent and shell panes. Only the character set
+ * is set (`LC_CTYPE`): the operator's language and formats stay theirs.
+ */
+export declare function utf8Env<T extends Record<string, string | undefined>>(env: T): T;
+/**
+ * What only this daemon's own process needs, never a Code thread's terminal. The desktop app runs
+ * the CLI on its bundled Electron (`ELECTRON_RUN_AS_NODE=1`, `PROHOST_CLI_RUN=1`): passed on to the
+ * tmux server, every shell and agent pane would inherit them, and any Electron app started there
+ * (`electron .`, a dev build) would start as plain Node instead. The hook shim sets the one it needs.
+ */
+export declare const DAEMON_ONLY_ENV: readonly ["ELECTRON_RUN_AS_NODE", "PROHOST_CLI_RUN"];
+/** {@link utf8Env}, without {@link DAEMON_ONLY_ENV}: the env every tmux this host runs gets. */
+export declare function paneEnv<T extends Record<string, string | undefined>>(env: T): T;
+export declare function killSessionArgs(viewName: string): string[];
+/**
+ * Text relayed from a composer, as tmux commands: C0 control characters other
+ * than newline and tab are dropped — a reply is text, never a key sequence —
+ * and multi-line text goes in as one bracketed paste so the agent sees one
+ * message rather than one per line.
+ *
+ * Returns the commands to run in order; an entry with `stdin` feeds that text
+ * to tmux on standard input (`load-buffer -`). Enter is sent last, separately,
+ * so the agent submits what was pasted.
+ */
+export declare function sendTextCommands(name: string, rawText: string): {
+    args: string[];
+    stdin?: string;
+}[];
+export type ApprovalDecision = 'allow' | 'allow_session' | 'deny';
+export declare const APPROVAL_DECISIONS: ReadonlySet<string>;
+export declare function clampDim(raw: unknown, fallback: number): number;
+/**
+ * A text control frame. Input arrives as binary or `input`; `hello` says what the viewer is and
+ * `claim` asks to size the window to it (see `sizing.ts`); `history` asks for the pane's
+ * scroll-back as text (`history.ts`). Anything else is ignored.
+ */
+export type ControlFrame = {
+    type: 'resize';
+    cols: number;
+    rows: number;
+} | {
+    type: 'input';
+    data: string;
+} | {
+    type: 'hello';
+    client: ViewerClient;
+} | {
+    type: 'claim';
+} | {
+    type: 'history';
+    id: string;
+    lines: number;
+} | {
+    type: 'ping';
+} | {
+    type: 'pong';
+};
+export declare function parseControl(text: string): ControlFrame | null;
+/**
+ * Whether a viewer's keystrokes stop the agent's turn: a lone Esc (Claude
+ * Code's interrupt) or a Ctrl+C anywhere in the chunk. Esc as the first byte of
+ * a longer sequence is an arrow key or a terminal report, not an interrupt.
+ */
+export declare function isInterruptInput(data: Uint8Array): boolean;
+/** Whether `data` holds anything a person typed: what is left once the emulator's own reports are taken out. */
+export declare function isHumanInput(data: Uint8Array): boolean;
+/** A focus-in report (`focus-events on`): the viewer's terminal just got focus, which claims the window's size. */
+export declare function hasFocusIn(data: Uint8Array): boolean;
+/**
+ * Whether `data` may have put the pane in copy mode: a mouse report (a wheel step up or a drag
+ * enters it, `mouse on`) or tmux's prefix key (C-b [). Typed input that follows leaves it first.
+ */
+export declare function mayEnterCopyMode(data: Uint8Array): boolean;
+/**
+ * Text a person typed (or pasted) for the program in the pane: a chunk that holds a printable
+ * character and isn't an escape sequence (arrows, PgUp, function keys move through copy mode) —
+ * except a bracketed paste (`ESC [200~`…), which is text.
+ */
+export declare function isTypedText(data: Uint8Array): boolean;
+/**
+ * A gesture that scrolls (or drags in) the pane — what makes a viewer "the one who scrolled": a wheel
+ * step or a drag (an SGR or X10 mouse report with button 32 and up), or the prefix key. A plain
+ * click is not one.
+ */
+export declare function isScrollGesture(data: Uint8Array): boolean;
+/**
+ * The keys a person presses to leave copy mode (q, Esc, Ctrl+C): typed while the pane was in it,
+ * they only leave it, as they did before — never reach the agent as a keystroke or an interrupt.
+ */
+export declare function isCopyModeExitKey(data: Uint8Array): boolean;
+/** `1` when the window's pane is in a mode (copy mode, after a scroll back). */
+export declare function paneInModeArgs(name: string): string[];
+/** Leave copy mode, if the pane is in it, before relayed text is typed (it would be read as copy-mode keys). */
+export declare function leaveCopyModeArgs(name: string): string[];

package/dist/codehost/tmux.js

@@ -0,0 +1,394 @@
+/**
+ * Pure tmux helpers for the Mac terminal host — the same shape as the cloud
+ * sandbox's terminal server (`shared/sandbox/template_coding/terminal-server/lib.js`),
+ * ported here rather than imported: the CLI ships on npm on its own.
+ *
+ * Same names as the sandbox — session `prohost`, viewers attached as grouped
+ * sessions so each keeps its own current window — with two differences a
+ * shared machine needs:
+ *
+ * - **Its own tmux server** (`tmux -L prohost-<home digest>`). The operator's own tmux, its
+ *   sessions and its config are never touched, and nothing here can be
+ *   attached to by accident from their terminal.
+ * - **A window per thread**, not one `agent` window per sandbox: `a-<terminal>`
+ *   runs the agent, `s-<terminal>` is a shell in the same worktree, made the
+ *   first time someone asks for it.
+ *
+ * tmux owns the processes, so a thread outlives the daemon: a restarted daemon
+ * finds its windows again with {@link listWindowsArgs} and the `@prohost_*`
+ * window options set at creation.
+ */
+import crypto from 'node:crypto';
+import { parseHistoryRequest } from './history.js';
+import { parseViewerClient } from './sizing.js';
+/** Prefix of `tmux -L <socket>`: this host's private tmux server (one per `$PROHOST_HOME`). */
+export const TMUX_SOCKET_PREFIX = 'prohost';
+export const TMUX_SESSION = 'prohost';
+/** The window the session is created with, so it exists while no thread runs. */
+export const HOME_WINDOW = 'home';
+export const TERMINAL_WINDOWS = new Set(['agent', 'shell']);
+/** Terminal and thread ids: what tmux names, env values and URL paths can all carry as-is. */
+export const ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+export const DEFAULT_COLS = 120;
+export const DEFAULT_ROWS = 32;
+export const MAX_DIM = 1000;
+/**
+ * The private server's config, written beside the settings and passed with
+ * `-f`. Mirrors `shared/sandbox/template_coding/tmux.conf`, except for sizing
+ * (each window is made `window-size manual` and sized by the host, see
+ * `sizing.ts`), the hidden window-edge border and copy-mode position box, and
+ * `scroll-on-clear off` (Mac-only for now: the sandbox config is rebuilt with
+ * its template).
+ */
+export const TMUX_CONF = `# Written by \`prohost agent run\` for this machine's Code-thread terminals.
+# A private tmux server (tmux -L ${TMUX_SOCKET_PREFIX}-…); your own tmux is not affected.
+set -g status off
+# Esc must reach Claude Code immediately (it interrupts a turn).
+set -s escape-time 10
+set -g default-terminal "tmux-256color"
+set -g history-limit 50000
+# Claude Code clears the whole screen and redraws it on every width change; with this on
+# (tmux's default) each old screen was kept in scrollback, so its header showed up once per
+# resize. A redraw longer than the screen still scrolls into history, so the host also keeps
+# width changes few (\`sizing.ts\`). -q: tmux before 3.3 has no such option.
+set -gq scroll-on-clear off
+set -g mouse on
+# Three lines per wheel step, as in a native terminal; tmux's five makes a
+# trackpad jump. Both copy-mode tables: mode-keys follows $EDITOR.
+bind -T copy-mode WheelUpPane select-pane \\; send-keys -X -N 3 scroll-up
+bind -T copy-mode WheelDownPane select-pane \\; send-keys -X -N 3 scroll-down
+bind -T copy-mode-vi WheelUpPane select-pane \\; send-keys -X -N 3 scroll-up
+bind -T copy-mode-vi WheelDownPane select-pane \\; send-keys -X -N 3 scroll-down
+# A program in the pane may not set anyone's clipboard through tmux: OSC 52
+# from the pane is ignored. Pinned rather than left to the default, which was
+# \`on\` before tmux 2.6. tmux still offers its own copies to the attached
+# terminal as OSC 52; whether a viewer writes them to the system clipboard is
+# that viewer's choice (the web terminal's gated clipboard addon, #21271).
+# The default drag binding is kept on purpose: it leaves copy mode on mouse-up,
+# so the next keystroke (a person's, or a relayed reply's) reaches the agent.
+set -s set-clipboard external
+# Windows are sized by the host, never by whichever viewer was active last: it
+# picks one viewer per window (the first to show it, then whoever types, focuses
+# or asks) and resizes the window to it (\`sizing.ts\`); \`resize-window\` makes
+# that window \`window-size manual\`. A new window is resized at once to the
+# size it will be viewed at. Not manual globally: tmux 3.4's server exits at
+# start with that in its config.
+set -g window-size latest
+# A viewer bigger than the window (someone smaller sizes it) sees blank space
+# beyond it, not tmux's dotted fill. -q: tmux before 3.3 has no such option.
+set -gq fill-character " "
+# ...and no border at the window's edge: tmux draws one there in the active
+# border's green. Spaces in the terminal's own colours instead.
+set -g pane-border-style default
+set -g pane-active-border-style default
+set -gq pane-border-lines spaces
+setw -g aggressive-resize on
+# Scrolling back (copy mode) shows no "[4/120]" position box over the agent's
+# screen. -q: an older tmux has no such option (and shows the box).
+set -gq copy-mode-position-format ""
+# Window names are an API (the host targets them by name) — nothing may rename them.
+setw -g automatic-rename off
+setw -g allow-rename off
+set -g set-titles off
+set -g focus-events on
+`;
+export function isValidId(value) {
+    return typeof value === 'string' && ID_PATTERN.test(value);
+}
+/** tmux window name for one of a thread's windows. */
+export function windowName(terminalId, window) {
+    if (!isValidId(terminalId))
+        throw new Error('invalid terminal id');
+    return `${window === 'agent' ? 'a' : 's'}-${terminalId}`;
+}
+/** `prohost:<window>` — an exact target, never a prefix match. */
+export function windowTarget(name) {
+    // `=` makes tmux match the name exactly: `a-1` must not resolve to `a-10`.
+    return `${TMUX_SESSION}:=${name}`;
+}
+/**
+ * The private server's socket name for one `$PROHOST_HOME`. Two agent homes on
+ * one machine (the desktop app's and a terminal's) must not manage one
+ * server's windows: each hook would read the other's token.
+ */
+export function socketNameFor(home) {
+    return `${TMUX_SOCKET_PREFIX}-${crypto.createHash('sha256').update(home).digest('hex').slice(0, 10)}`;
+}
+/** Arguments every invocation starts with. */
+export function baseArgs(socket, confPath) {
+    return ['-L', socket, '-f', confPath];
+}
+export function hasSessionArgs() {
+    return ['has-session', '-t', `=${TMUX_SESSION}`];
+}
+export function newSessionArgs(cwd) {
+    return ['new-session', '-d', '-s', TMUX_SESSION, '-n', HOME_WINDOW, '-c', cwd];
+}
+export function newWindowArgs(spec) {
+    const env = Object.entries(spec.env).flatMap(([key, value]) => ['-e', `${key}=${value}`]);
+    return ['new-window', '-d', '-t', `${TMUX_SESSION}:`, '-n', spec.name, '-c', spec.cwd, ...env, spec.command];
+}
+export function setWindowMetaArgs(name, meta) {
+    const target = windowTarget(name);
+    return [
+        ['set-option', '-w', '-t', target, '@prohost_terminal', meta.terminalId],
+        ['set-option', '-w', '-t', target, '@prohost_thread', meta.codeThreadId],
+        ['set-option', '-w', '-t', target, '@prohost_agent', meta.agent],
+        ['set-option', '-w', '-t', target, '@prohost_cwd', meta.cwd],
+        ...(meta.readyMark ? [['set-option', '-w', '-t', target, '@prohost_ready_mark', '1']] : []),
+    ];
+}
+const LIST_FORMAT = '#{window_name}\t#{@prohost_terminal}\t#{@prohost_thread}\t#{@prohost_agent}\t#{@prohost_cwd}' +
+    '\t#{@prohost_ready_mark}\t#{pane_pid}';
+export function listWindowsArgs() {
+    return ['list-windows', '-t', `=${TMUX_SESSION}`, '-F', LIST_FORMAT];
+}
+/** Parse {@link listWindowsArgs} output; windows without valid metadata keep only their name. */
+export function parseListWindows(stdout) {
+    const windows = [];
+    for (const line of stdout.split('\n')) {
+        if (!line.trim())
+            continue;
+        const [name = '', terminalId = '', codeThreadId = '', agent = '', cwd = '', readyMark = '', pid = ''] = line.split('\t');
+        if (!name)
+            continue;
+        const meta = isValidId(terminalId) && isValidId(codeThreadId) && agent && cwd
+            ? {
+                terminalId,
+                codeThreadId,
+                agent,
+                cwd,
+                ...(readyMark === '1' ? { readyMark: true } : {}),
+            }
+            : undefined;
+        const panePid = /^\d+$/.test(pid) ? Number(pid) : undefined;
+        windows.push({ name, ...(meta ? { meta } : {}), ...(panePid ? { panePid } : {}) });
+    }
+    return windows;
+}
+/** A fresh, unguessable name for one viewer's grouped session. */
+export function viewSessionName() {
+    return `view-${crypto.randomBytes(6).toString('hex')}`;
+}
+/**
+ * argv (after {@link baseArgs}) that attaches one viewer to window `name`.
+ *
+ * A grouped session (`new-session -t prohost`), as in the sandbox: it shares
+ * every window but keeps its own current window, so one viewer on a shell
+ * never moves another off the agent. `destroy-unattached` reaps it when the
+ * viewer goes. `-u`: the viewer is xterm.js, which is always UTF-8 (see
+ * {@link utf8Env}).
+ */
+export function attachArgs(name, viewName) {
+    return [
+        '-u',
+        'new-session',
+        '-t',
+        `=${TMUX_SESSION}`,
+        '-s',
+        viewName,
+        ';',
+        'set-option',
+        'destroy-unattached',
+        'on',
+        ';',
+        'select-window',
+        '-t',
+        `${viewName}:=${name}`,
+    ];
+}
+/** What tmux and its panes run under when the daemon's own env has no UTF-8 locale. */
+export const UTF8_CTYPE = 'C.UTF-8';
+/**
+ * `env` with a UTF-8 character locale, for every tmux this host runs.
+ *
+ * A daemon started by launchd (or any GUI parent) usually has no LANG at all,
+ * and a tmux client without a UTF-8 locale draws every non-ASCII cell as `_` —
+ * Claude Code's ⏺ bullets, its logo, an em dash. The server that client starts
+ * passes the same locale to the agent and shell panes. Only the character set
+ * is set (`LC_CTYPE`): the operator's language and formats stay theirs.
+ */
+export function utf8Env(env) {
+    const ctype = env.LC_ALL || env.LC_CTYPE || env.LANG || '';
+    if (/utf-?8/i.test(ctype))
+        return env;
+    const out = { ...env, LC_CTYPE: UTF8_CTYPE };
+    // A non-UTF-8 LC_ALL would outrank it.
+    delete out.LC_ALL;
+    return out;
+}
+/**
+ * What only this daemon's own process needs, never a Code thread's terminal. The desktop app runs
+ * the CLI on its bundled Electron (`ELECTRON_RUN_AS_NODE=1`, `PROHOST_CLI_RUN=1`): passed on to the
+ * tmux server, every shell and agent pane would inherit them, and any Electron app started there
+ * (`electron .`, a dev build) would start as plain Node instead. The hook shim sets the one it needs.
+ */
+export const DAEMON_ONLY_ENV = ['ELECTRON_RUN_AS_NODE', 'PROHOST_CLI_RUN'];
+/** {@link utf8Env}, without {@link DAEMON_ONLY_ENV}: the env every tmux this host runs gets. */
+export function paneEnv(env) {
+    const out = { ...env };
+    for (const key of DAEMON_ONLY_ENV)
+        delete out[key];
+    return utf8Env(out);
+}
+export function killSessionArgs(viewName) {
+    return ['kill-session', '-t', `=${viewName}`];
+}
+/**
+ * Text relayed from a composer, as tmux commands: C0 control characters other
+ * than newline and tab are dropped — a reply is text, never a key sequence —
+ * and multi-line text goes in as one bracketed paste so the agent sees one
+ * message rather than one per line.
+ *
+ * Returns the commands to run in order; an entry with `stdin` feeds that text
+ * to tmux on standard input (`load-buffer -`). Enter is sent last, separately,
+ * so the agent submits what was pasted.
+ */
+export function sendTextCommands(name, rawText) {
+    // eslint-disable-next-line no-control-regex
+    const text = rawText.replace(/\r\n?/g, '\n').replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, '');
+    const target = windowTarget(name);
+    if (!text.trim())
+        return [];
+    if (!text.includes('\n')) {
+        return [
+            { args: ['send-keys', '-t', target, '-l', '--', text] },
+            { args: ['send-keys', '-t', target, 'Enter'] },
+        ];
+    }
+    const buffer = `prohost-${crypto.randomBytes(4).toString('hex')}`;
+    return [
+        { args: ['load-buffer', '-b', buffer, '-'], stdin: text },
+        // -p: bracketed paste when the application asked for it; -d: delete the buffer after.
+        { args: ['paste-buffer', '-p', '-d', '-b', buffer, '-t', target] },
+        { args: ['send-keys', '-t', target, 'Enter'] },
+    ];
+}
+export const APPROVAL_DECISIONS = new Set(['allow', 'allow_session', 'deny']);
+export function clampDim(raw, fallback) {
+    const n = typeof raw === 'number' ? Math.trunc(raw) : Number.parseInt(String(raw ?? ''), 10);
+    if (!Number.isFinite(n) || n < 1)
+        return fallback;
+    return Math.min(n, MAX_DIM);
+}
+export function parseControl(text) {
+    let frame;
+    try {
+        frame = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!frame || typeof frame !== 'object')
+        return null;
+    const f = frame;
+    if (f.type === 'resize') {
+        const cols = clampDim(f.cols, 0);
+        const rows = clampDim(f.rows, 0);
+        return cols && rows ? { type: 'resize', cols, rows } : null;
+    }
+    if (f.type === 'input' && typeof f.data === 'string')
+        return { type: 'input', data: f.data };
+    if (f.type === 'hello')
+        return { type: 'hello', client: parseViewerClient(f.client) };
+    if (f.type === 'claim')
+        return { type: 'claim' };
+    if (f.type === 'history')
+        return parseHistoryRequest(f);
+    if (f.type === 'ping' || f.type === 'pong')
+        return { type: f.type };
+    return null;
+}
+/**
+ * Whether a viewer's keystrokes stop the agent's turn: a lone Esc (Claude
+ * Code's interrupt) or a Ctrl+C anywhere in the chunk. Esc as the first byte of
+ * a longer sequence is an arrow key or a terminal report, not an interrupt.
+ */
+export function isInterruptInput(data) {
+    if (data.length === 1 && data[0] === 0x1b)
+        return true;
+    return data.includes(0x03);
+}
+/**
+ * What a terminal emulator sends on its own, never a person: focus in/out
+ * (`focus-events on`), cursor-position and status replies, device-attribute
+ * and mode reports, window-size reports, mouse reports (`mouse on`: a click
+ * or a wheel step is reported, not typed), and OSC/DCS replies such as a
+ * colour query's answer. Several can arrive in one chunk. The same set as
+ * the web terminal's `AUTOMATIC_TERMINAL_SEQUENCE` (`web/src/features/coding/
+ * utils/terminalKeys.ts`); xterm.js hands each report to `onData` whole.
+ */
+const AUTOMATIC_REPORTS = new RegExp([
+    /\x1b\[[IO]/, // focus in / out
+    /\x1b\[\??\d+(?:;\d+){1,2}R/, // cursor position report, and xterm's DEC form (DECXCPR)
+    /\x1b\[\??\d*n/, // device status report reply
+    /\x1b\[[?>=][\d;]*c/, // primary / secondary / tertiary device attributes
+    /\x1b\[\??[\d;]*\$y/, // mode report (DECRPM)
+    /\x1b\[\d+(?:;\d+)*t/, // window size / position report
+    /\x1b\[<\d+;\d+;\d+[Mm]/, // SGR mouse report
+    /\x1b\[M[\s\S]{3}/, // X10 mouse report
+    /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/, // OSC reply (colours, clipboard query)
+    /\x1bP[^\x1b]*\x1b\\/, // DCS reply (terminal version, setting query)
+]
+    .map((pattern) => pattern.source)
+    .join('|'), 'g');
+/** Whether `data` holds anything a person typed: what is left once the emulator's own reports are taken out. */
+export function isHumanInput(data) {
+    return Buffer.from(data).toString('latin1').replace(AUTOMATIC_REPORTS, '').length > 0;
+}
+/** A focus-in report (`focus-events on`): the viewer's terminal just got focus, which claims the window's size. */
+export function hasFocusIn(data) {
+    return Buffer.from(data).toString('latin1').includes('\x1b[I');
+}
+/**
+ * Whether `data` may have put the pane in copy mode: a mouse report (a wheel step up or a drag
+ * enters it, `mouse on`) or tmux's prefix key (C-b [). Typed input that follows leaves it first.
+ */
+export function mayEnterCopyMode(data) {
+    return data.includes(0x02) || /\x1b\[<\d+;\d+;\d+[Mm]|\x1b\[M/.test(Buffer.from(data).toString('latin1'));
+}
+/**
+ * Text a person typed (or pasted) for the program in the pane: a chunk that holds a printable
+ * character and isn't an escape sequence (arrows, PgUp, function keys move through copy mode) —
+ * except a bracketed paste (`ESC [200~`…), which is text.
+ */
+export function isTypedText(data) {
+    if (data.length === 0)
+        return false;
+    if (data[0] === 0x1b && !Buffer.from(data).toString('latin1').startsWith('\x1b[200~'))
+        return false;
+    return data.some((byte) => byte >= 0x20 && byte !== 0x7f);
+}
+/**
+ * A gesture that scrolls (or drags in) the pane — what makes a viewer "the one who scrolled": a wheel
+ * step or a drag (an SGR or X10 mouse report with button 32 and up), or the prefix key. A plain
+ * click is not one.
+ */
+export function isScrollGesture(data) {
+    if (data.includes(0x02))
+        return true;
+    const text = Buffer.from(data).toString('latin1');
+    for (const match of text.matchAll(/\x1b\[<(\d+);\d+;\d+[Mm]/g))
+        if (Number(match[1]) >= 32)
+            return true;
+    for (const match of text.matchAll(/\x1b\[M([\s\S])[\s\S]{2}/g))
+        if (match[1].charCodeAt(0) - 32 >= 32)
+            return true;
+    return false;
+}
+/**
+ * The keys a person presses to leave copy mode (q, Esc, Ctrl+C): typed while the pane was in it,
+ * they only leave it, as they did before — never reach the agent as a keystroke or an interrupt.
+ */
+export function isCopyModeExitKey(data) {
+    return data.length === 1 && (data[0] === 0x71 || data[0] === 0x1b || data[0] === 0x03);
+}
+/** `1` when the window's pane is in a mode (copy mode, after a scroll back). */
+export function paneInModeArgs(name) {
+    return ['display-message', '-p', '-t', windowTarget(name), '#{pane_in_mode}'];
+}
+/** Leave copy mode, if the pane is in it, before relayed text is typed (it would be read as copy-mode keys). */
+export function leaveCopyModeArgs(name) {
+    const target = windowTarget(name);
+    return ['if-shell', '-F', '-t', target, '#{pane_in_mode}', `send-keys -X -t ${target} cancel`];
+}

package/dist/index.d.ts

@@ -22,6 +22,11 @@ interface ParsedArgs {
     flags: Record<string, string | boolean>;
 }
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+/**
+ * The `hook` command's arguments as the hook reads them: its positionals, and
+ * the PermissionRequest hook's `--wait` (which `parseArgs` keeps as a flag).
+ */
+export declare function hookArgs({ subcommand, args, flags }: ParsedArgs): string[];
 declare function main(argv: readonly string[]): Promise<number>;
 export { main };
 /**

package/dist/index.js

@@ -18,6 +18,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { endpointProblem } from './agent/base-url.js';
 import { runAgent } from './agent/command.js';
+import { runHook } from './codehost/hooks.js';
 import { DEFAULT_WS_URL, runListen } from './listen.js';
 import { runUsage } from './usage/command.js';
 import { CLI_VERSION } from './version.js';
@@ -31,12 +32,17 @@ function printHelp() {
         '                     [--webhook-url <https-url>] [--base-url <url>]',
         "  prohost agent run --exec '<command>' [--concurrency <n>] [--repos <checkout,…>] [--idle-timeout <seconds>]",
         '                    [--timeout <seconds>] [--dry-run] [--workdir <dir>]',
+        '  prohost agent run --host-only [--repos <checkout,…>] [--machine <name>]   Host Code threads only; run nothing',
         "  prohost agent install-daemon --exec '<command>' [--workdir <dir>] [--account <label>]   Keep the agent running",
+        '  prohost agent install-daemon --host-only [--machine <name>]',
         '  prohost agent uninstall-daemon',
         '  prohost agent account add <label> --runtime claude|codex [--billing subscription|api_key]',
         '  prohost agent account list | remove <label>',
         '  prohost agent list                   Every paired agent on this machine, and its accounts',
         '  prohost agent workspace init --developer --repo <checkout> [--workdir <dir>]',
+        '  prohost agent code-host status | enable [--allow-remote-terminal] | remote on|off | disable',
+        '                                       Host Code threads (agent terminals) on this Mac; off by default',
+        '  prohost agent code-host folders add <path> | list [--json] | remove <path>',
         '  prohost usage connect [--key -] [--base-url <url>]   Report AI usage without pairing an agent (prompts for the key; --key - reads it from stdin)',
         '  prohost usage discover [--dry-run] | start [--once] [--machine <name>] | status',
         '  prohost usage install-daemon [--machine <name>] | uninstall-daemon',
@@ -73,6 +79,9 @@ function printHelp() {
         '                   its own `git worktree` of every one under $PROHOST_HOME/worktrees, kept for',
         '                   the life of the thread and removed after 14 idle days if it is clean. The',
         '                   agent is told to work there and to leave the originals alone.',
+        '  --host-only      Instead of --exec: host Code threads on this machine (terminals you open',
+        '                   from ProhostAI) and execute nothing anyone sends. Every run requested of',
+        '                   this agent — a mention, a DM — is closed at once as refused.',
         '  --dry-run        Print the reply that would be posted; write nothing.',
         '  --workdir        Working directory for the agent command. Defaults to $PROHOST_HOME/workspace.',
         '                   Avoid pointing it at a code checkout: agents read CLAUDE.md, .claude/settings.json',
@@ -183,6 +192,14 @@ export function parseArgs(argv) {
     }
     return { command, subcommand, args, flags };
 }
+/**
+ * The `hook` command's arguments as the hook reads them: its positionals, and
+ * the PermissionRequest hook's `--wait` (which `parseArgs` keeps as a flag).
+ */
+export function hookArgs({ subcommand, args, flags }) {
+    const wait = flags.wait;
+    return [subcommand ?? '', ...args, ...(typeof wait === 'string' ? ['--wait', wait] : [])];
+}
 async function main(argv) {
     const { command, subcommand, args, flags } = parseArgs(argv);
     // Checked before the help/no-command branch: `prohost --version` carries no
@@ -209,6 +226,10 @@ async function main(argv) {
     if (command === 'usage') {
         return runUsage(subcommand, flags, printHelp);
     }
+    // Run by the Code-thread hook shim (codehost/hooks.ts), not by people; not in --help.
+    if (command === 'hook') {
+        return runHook(hookArgs({ command, subcommand, args, flags }));
+    }
     if (command !== 'listen') {
         process.stderr.write(`Unknown command: ${command}\n\n`);
         printHelp();