termdock 1.3.1 → 1.4.0

package/dist/server/agent/registry.js

@@ -0,0 +1,244 @@
+/**
+ * Third-party CLI coding-agent registry + detection.
+ * （设计移植自 tty7 的 core/cli_agent.rs，Apache-2.0；此处为 TypeScript 重写）
+ *
+ * termdock recognizes when a pane is running a known coding agent (Claude
+ * Code, Codex, Gemini CLI, …) so the tab can brand it and notifications can
+ * say *which* agent finished or needs you. Detection is a pure function over
+ * the foreground process's argv (which the server already polls for program
+ * labels), so it works identically in shell mode and tmux mode.
+ *
+ * Strategy:
+ * 1. Strip leading `VAR=value` environment assignments.
+ * 2. If the launcher's own basename matches a known agent, that's it.
+ * 3. Otherwise only if the launcher is a script *interpreter* (node, bun,
+ *    python, npx, …), scan remaining path-like arguments for a segment that
+ *    names an agent — the npm/pip-wrapped case (`node …/claude-code/cli.js`).
+ *    The interpreter gate keeps `cat codex.md` from false-matching.
+ * 4. User-defined rules (`agentCommands` in program-detection config): a map
+ *    from command basename to agent slug, for personal wrappers (`cc`).
+ */
+// Registry order matters only for iteration stability; lookup is by alias.
+// flexoki-allow-file — vendor brand accents are deliberately theme-independent.
+const AGENTS = [
+    { slug: 'claude', displayName: 'Claude Code', aliases: ['claude', 'claude-code'], accentColor: '#D97757', icon: 'claude' },
+    { slug: 'codex', displayName: 'Codex', aliases: ['codex', 'codex-cli'], accentColor: '#000000', icon: 'codex' },
+    { slug: 'gemini', displayName: 'Gemini', aliases: ['gemini', 'gemini-cli'], accentColor: '#4285F4', icon: 'gemini' },
+    { slug: 'aider', displayName: 'Aider', aliases: ['aider', 'aider-chat'], accentColor: '#14B8A6', icon: null },
+    { slug: 'amp', displayName: 'Amp', aliases: ['amp'], accentColor: '#F34E3F', icon: 'amp' },
+    { slug: 'opencode', displayName: 'OpenCode', aliases: ['opencode'], accentColor: '#6E56CF', icon: 'opencode' },
+    { slug: 'copilot', displayName: 'Copilot', aliases: ['copilot'], accentColor: '#8957E5', icon: 'copilot' },
+    { slug: 'cursor', displayName: 'Cursor', aliases: ['cursor-agent'], accentColor: '#9AA0A6', icon: 'cursor' },
+    { slug: 'goose', displayName: 'Goose', aliases: ['goose'], accentColor: '#9A8CFF', icon: 'goose' },
+    { slug: 'droid', displayName: 'Droid', aliases: ['droid'], accentColor: '#F59E0B', icon: 'droid' },
+    { slug: 'pi', displayName: 'Pi', aliases: ['pi'], accentColor: '#0EA5E9', icon: null },
+    { slug: 'auggie', displayName: 'Auggie', aliases: ['auggie'], accentColor: '#16A34A', icon: null },
+    { slug: 'hermes', displayName: 'Hermes', aliases: ['hermes'], accentColor: '#8B5CF6', icon: null },
+    { slug: 'vibe', displayName: 'Vibe', aliases: ['vibe', 'vibe-acp'], accentColor: '#FF7000', icon: null },
+    { slug: 'antigravity', displayName: 'Antigravity', aliases: ['agy', 'antigravity'], accentColor: '#2563EB', icon: null },
+    { slug: 'grok', displayName: 'Grok', aliases: ['grok'], accentColor: '#000000', icon: 'grok' },
+    { slug: 'qwen', displayName: 'Qwen Code', aliases: ['qwen', 'qwen-code'], accentColor: '#7C3AED', icon: null },
+];
+const BY_ALIAS = new Map();
+const BY_SLUG = new Map();
+for (const info of AGENTS) {
+    BY_SLUG.set(info.slug, info);
+    for (const alias of info.aliases)
+        BY_ALIAS.set(alias, info);
+}
+export function agentBySlug(slug) {
+    if (!slug)
+        return null;
+    return BY_SLUG.get(slug.trim().toLowerCase()) ?? null;
+}
+export function listAgents() {
+    return AGENTS.slice();
+}
+function matchToken(token) {
+    return BY_ALIAS.get(token) ?? null;
+}
+/** A `KEY=value` shell environment assignment prefix (`FOO=bar cmd`). */
+function isEnvAssignment(token) {
+    const eq = token.indexOf('=');
+    if (eq <= 0)
+        return false;
+    const key = token.slice(0, eq);
+    if (!/^[A-Za-z_]/.test(key))
+        return false;
+    return /^[A-Za-z0-9_]+$/.test(key);
+}
+/**
+ * The final path component with trailing script extension stripped.
+ * `/usr/bin/claude` → `claude`, `cli.js` → `cli`, `claude.cmd` → `claude`.
+ * Splits on both separators so Windows paths resolve the same on Unix.
+ */
+function baseStem(token) {
+    const trimmed = token.replace(/[/\\]+$/, '');
+    const idx = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+    const name = idx >= 0 ? trimmed.slice(idx + 1) : trimmed;
+    for (const ext of ['.js', '.mjs', '.cjs', '.ts', '.py', '.rb', '.sh', '.exe', '.cmd', '.bat', '.ps1']) {
+        if (name.endsWith(ext))
+            return name.slice(0, -ext.length);
+    }
+    return name;
+}
+/** Whether a launcher basename is an interpreter whose arguments name the real program. */
+function isInterpreter(stem) {
+    return ['node', 'nodejs', 'bun', 'deno', 'npx', 'pnpm', 'yarn',
+        'python', 'python3', 'ruby', 'uv', 'uvx', 'env'].includes(stem.toLowerCase());
+}
+function tokenNamesAgent(token, agent) {
+    return token.split(/[/\\]/).some((seg) => matchToken(baseStem(seg).toLowerCase()) === agent);
+}
+/**
+ * Identify the coding agent a foreground argv is running, or null.
+ * `customRules` maps a command basename to an agent slug (personal wrappers);
+ * applies to the launcher only and loses to a built-in match on the same name.
+ */
+export function detectAgentFromArgv(argv, customRules = {}) {
+    let i = 0;
+    while (i < argv.length && isEnvAssignment(argv[i]))
+        i++;
+    const launcher = argv[i];
+    if (!launcher)
+        return null;
+    const launcherStem = baseStem(launcher);
+    // Native binary (or built-in match wins over custom rules on the same name)
+    const direct = matchToken(launcherStem.toLowerCase());
+    if (direct)
+        return direct;
+    const custom = customRules[launcherStem.toLowerCase()];
+    if (custom) {
+        const agent = agentBySlug(custom);
+        if (agent)
+            return agent;
+    }
+    // Interpreter wrapper: scan the script path / package args it runs
+    if (isInterpreter(launcherStem)) {
+        for (let j = i + 1; j < argv.length; j++) {
+            const arg = argv[j];
+            if (arg.startsWith('-'))
+                continue;
+            for (const seg of arg.split(/[/\\]/)) {
+                const hit = matchToken(baseStem(seg).toLowerCase());
+                if (hit)
+                    return hit;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Shell-split a raw command line (as captured from ps args) into argv, then
+ * detect. Naive tokenization: whitespace split, quotes trimmed — enough for
+ * the dominant shapes (`claude --model opus`, `node /path/cli.js --flag`).
+ */
+export function detectAgentFromCommand(command, customRules = {}) {
+    const argv = command
+        .split(/\s+/)
+        .map((t) => t.replace(/^["']+|["']+$/g, ''))
+        .filter((t) => t.length > 0);
+    return detectAgentFromArgv(argv, customRules);
+}
+// ---------------------------------------------------------------------------
+// Resume: rebuild the shell command that resumes a previous agent session by
+// its native session id, carrying the user's original launch flags.
+// ---------------------------------------------------------------------------
+/** Per-agent resume command templates; null = no known resume flag. */
+function resumeCommandFor(agent, sessionId, flags) {
+    const f = flags.length > 0 ? ' ' + flags.join(' ') : '';
+    switch (agent.slug) {
+        case 'claude': return `claude${f} --resume ${sessionId}`;
+        // Codex resumes via a subcommand; interactive options follow the positional id
+        case 'codex': return `codex resume ${sessionId}${f}`;
+        case 'gemini': return `gemini${f} --resume ${sessionId}`;
+        case 'opencode': return `opencode${f} --session ${sessionId}`;
+        case 'amp': return `amp threads continue ${sessionId}${f}`;
+        case 'cursor': return `cursor-agent${f} --resume ${sessionId}`;
+        case 'copilot': return `copilot${f} --resume ${sessionId}`;
+        case 'grok': return `grok${f} --resume ${sessionId}`;
+        default: return null;
+    }
+}
+/** Session-targeting flags whose old value must not survive onto a resume. */
+const STALE_SESSION_FLAGS = {
+    claude: ['--resume', '-r', '--continue', '-c', '--session-id', '--from-pr'],
+    gemini: ['--resume', '-r'],
+    cursor: ['--resume', '-r'],
+    copilot: ['--resume', '-r', '--continue', '-c'],
+    opencode: ['--session', '-s', '--continue', '-c'],
+    codex: ['--last'],
+    grok: ['--resume', '-r', '--load', '--continue', '-c', '--session-id', '-s',
+        '--fork-session', '--worktree', '-w', '--worktree-ref', '--ref'],
+};
+/**
+ * The launch-flag tail of argv worth replaying on a resume command, or null
+ * to resume bare. Deliberately conservative: anything ambiguous falls back to
+ * no flags rather than a corrupted command line.
+ * - The tail is everything after the token that names this agent; leading
+ *   `VAR=value` env assignments are skipped first. No naming token → null.
+ * - Stale session-targeting flags are stripped (the new id must win).
+ * - Every surviving token must be shell-safe, the first must be a `-` flag,
+ *   and no two bare words may run consecutively (a bare word is only valid as
+ *   the value directly behind a flag — anything else is a positional prompt
+ *   that must not re-submit itself into the resumed session).
+ */
+function replayFlags(agent, argv) {
+    let start = 0;
+    while (start < argv.length && isEnvAssignment(argv[start]))
+        start++;
+    let named = -1;
+    for (let j = start; j < argv.length; j++) {
+        if (tokenNamesAgent(argv[j], agent)) {
+            named = j;
+            break;
+        }
+    }
+    if (named < 0)
+        return null;
+    const tail = argv.slice(named + 1);
+    // A relaunched `codex resume <old-id>`: drop the subcommand and its id
+    if (agent.slug === 'codex' && tail[0] === 'resume') {
+        tail.shift();
+        if (tail.length > 0 && !tail[0].startsWith('-'))
+            tail.shift();
+    }
+    const stale = STALE_SESSION_FLAGS[agent.slug] ?? [];
+    for (let j = 0; j < tail.length;) {
+        const t = tail[j];
+        const isStale = stale.includes(t)
+            || stale.some((f) => f.length > 2 && t.startsWith(`${f}=`));
+        if (isStale) {
+            tail.splice(j, 1);
+            if (j < tail.length && !tail[j].startsWith('-'))
+                tail.splice(j, 1);
+        }
+        else {
+            j++;
+        }
+    }
+    // Safety gate: plain tokens only, flag-shaped tail
+    const safe = (t) => t.length > 0 && /^[A-Za-z0-9_=./,:@+~-]+$/.test(t);
+    if (!tail.every(safe))
+        return null;
+    let prevWasFlag = false;
+    for (const t of tail) {
+        const isFlag = t.startsWith('-');
+        if (!isFlag && !prevWasFlag)
+            return null;
+        prevWasFlag = isFlag;
+    }
+    return tail;
+}
+/**
+ * The shell command resuming a session, or null when the agent has no known
+ * resume flag or the id/flags aren't shell-safe. Ids come from the agent's own
+ * hook events but still land on a shell command line — refuse anything that
+ * isn't a plain token.
+ */
+export function buildResumeCommand(agent, sessionId, launchArgv) {
+    if (!sessionId || !/^[A-Za-z0-9._-]+$/.test(sessionId))
+        return null;
+    const flags = launchArgv ? replayFlags(agent, launchArgv) ?? [] : [];
+    return resumeCommandFor(agent, sessionId, flags);
+}

package/dist/server/agent/session.js

@@ -0,0 +1,162 @@
+/**
+ * Rich agent session status — the OSC 777 sentinel protocol + per-pane state
+ * machine. （设计移植自 tty7 core/cli_agent.rs，Apache-2.0；TypeScript 重写）
+ *
+ * Agent-side hooks (installed by `installers.ts`, or hand-wired) emit an
+ * OSC 777 notification whose title is AGENT_EVENT_SENTINEL and whose body is
+ * a small JSON event. The server sniffs those out of the PTY stream, folds
+ * them through `applyAgentEvent`, and streams state changes to clients for
+ * status dots, "needs your input" notifications, and session resume.
+ *
+ * Wire shape: `ESC ] 777 ; notify ; termdock://cli-agent ; {"v":1,…} BEL`
+ */
+import { agentBySlug } from './registry.js';
+export const AGENT_EVENT_SENTINEL = 'termdock://cli-agent';
+export const AGENT_EVENT_PROTOCOL_VERSION = 1;
+const EVENT_KINDS = new Set([
+    'session-start', 'prompt-submit', 'permission-request', 'question-asked',
+    'tool-complete', 'notification', 'stop', 'session-end',
+]);
+export function defaultAgentSessionState() {
+    return {
+        status: 'idle',
+        message: null,
+        sessionId: null,
+        launchArgv: null,
+        rich: false,
+        agentCwd: null,
+        activity: 0,
+    };
+}
+/**
+ * Fold one rich event into the state. Pure transition function — the caller
+ * owns *when* to call it and who to tell.
+ */
+export function applyAgentEvent(state, ev) {
+    state.rich = true;
+    if (ev.sessionId)
+        state.sessionId = ev.sessionId;
+    if (ev.cwd)
+        state.agentCwd = ev.cwd;
+    switch (ev.kind) {
+        case 'session-start':
+            state.status = 'idle';
+            state.message = null;
+            break;
+        case 'prompt-submit':
+            state.status = 'working';
+            state.message = null;
+            break;
+        // Explicit blocks from agents that distinguish them (Codex/OpenCode
+        // plugins): always the urgent "needs you" state.
+        case 'permission-request':
+        case 'question-asked':
+            state.status = 'waiting';
+            state.message = ev.message;
+            break;
+        // Claude Code overloads its single Notification hook: it fires *mid-turn*
+        // for a permission/decision prompt (a genuine block), but ALSO *between*
+        // turns as an idle "waiting for your input" reminder — which must not
+        // masquerade as a block. Escalate only when a turn is actually in flight;
+        // keyed on turn phase, not the message text, so it survives version/locale
+        // changes.
+        case 'notification':
+            if (state.status === 'working') {
+                state.status = 'waiting';
+                state.message = ev.message;
+            }
+            break;
+        // A tool call finished. Only meaningful as the recovery edge out of a
+        // block: the user answered the permission prompt, the approved tool ran,
+        // so the turn is moving again — no agent emits an explicit "permission
+        // replied" signal, so the next tool completion is that signal. Guarded on
+        // waiting so the steady stream of completions during normal work is a
+        // no-op and can never overwrite done between turns.
+        case 'tool-complete':
+            // The count moves even when the status doesn't: a tool call is the one
+            // signal that the working tree may have just changed mid-turn.
+            state.activity = (state.activity + 1) >>> 0;
+            if (state.status === 'waiting') {
+                state.status = 'working';
+                state.message = null;
+            }
+            break;
+        case 'stop':
+            state.status = 'done';
+            state.message = ev.message;
+            break;
+        // The agent session ended but its id stays: agents can resume an *ended*
+        // session, which is exactly what restore does. Its cwd claim does NOT
+        // stay: with no agent running, the pane's real directory is the truth.
+        case 'session-end':
+            state.status = 'idle';
+            state.message = null;
+            state.agentCwd = null;
+            break;
+    }
+}
+function nonEmpty(s) {
+    return typeof s === 'string' && s.trim().length > 0 ? s : null;
+}
+/**
+ * Parse a complete OSC payload (identifier included, e.g.
+ * `777;notify;termdock://cli-agent;{"v":1,…}`) into an AgentEvent. Returns
+ * null for anything that isn't a well-formed sentinel event — including
+ * unknown `event` values, so the protocol can grow without old servers
+ * mis-classifying new events.
+ */
+export function parseAgentEvent(payload) {
+    if (!payload.startsWith('777;notify;'))
+        return null;
+    const rest = payload.slice('777;notify;'.length);
+    if (!rest.startsWith(AGENT_EVENT_SENTINEL))
+        return null;
+    const json = rest.slice(AGENT_EVENT_SENTINEL.length);
+    if (!json.startsWith(';'))
+        return null;
+    let w;
+    try {
+        w = JSON.parse(json.slice(1));
+    }
+    catch {
+        return null;
+    }
+    if (!w || typeof w !== 'object')
+        return null;
+    const eventName = nonEmpty(w.event);
+    if (!eventName || !EVENT_KINDS.has(eventName))
+        return null;
+    return {
+        agent: agentBySlug(nonEmpty(w.agent)),
+        kind: eventName,
+        sessionId: nonEmpty(w.session_id),
+        message: nonEmpty(w.message),
+        cwd: nonEmpty(w.cwd),
+    };
+}
+/**
+ * Build the sentinel OSC sequence for one hook invocation — the emitter side,
+ * kept here so tests can round-trip it through `parseAgentEvent`.
+ * `payloadJson` is the hook's raw stdin JSON from the agent; fields are lifted
+ * into the sentinel body (snake_case, with camelCase aliases for Grok).
+ */
+export function buildHookSequence(agent, event, stdinJson) {
+    let payload = {};
+    try {
+        const parsed = JSON.parse(stdinJson);
+        if (parsed && typeof parsed === 'object')
+            payload = parsed;
+    }
+    catch { /* garbage stdin still yields a well-formed bare event */ }
+    const body = {
+        v: AGENT_EVENT_PROTOCOL_VERSION,
+        agent,
+        event,
+    };
+    for (const [key, alias] of [['session_id', 'sessionId'], ['message', 'message'], ['cwd', 'cwd']]) {
+        const v = nonEmpty(payload[key]) ?? nonEmpty(payload[alias]);
+        if (v)
+            body[key] = v;
+    }
+    return `\x1b]777;notify;${AGENT_EVENT_SENTINEL};${JSON.stringify(body)}\x07`;
+}

package/dist/server/agentHook.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * termdock agent-hook emitter — the agent-side half of the rich status channel.
+ * （设计移植自 tty7 core/agent_hooks.rs，Apache-2.0；TypeScript/Node 重写）
+ *
+ * Invoked by agent hooks as: `node agentHook.js <agent> <event>`.
+ * Reads the hook's JSON payload from stdin, builds one sentinel OSC 777
+ * sequence, and writes it to the controlling terminal, where the termdock
+ * server sniffs it out of the PTY stream and folds it into the pane's
+ * session state.
+ *
+ * Emission is gated on the TERMDOCK environment variable (injected into every
+ * shell termdock spawns / every managed tmux session), so hooks installed
+ * globally stay silent when an agent runs in another terminal.
+ *
+ * Always exits 0 quietly — a hook that fails must never break the agent's
+ * own flow (agents surface nonzero exits).
+ *
+ * This entry must stay dependency-light (fast cold start): only stdlib +
+ * the pure protocol module.
+ */
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { buildHookSequence } from './agent/session.js';
+/** The env var termdock sets in every spawned shell; the emitter refuses to
+ *  write escape sequences into terminals that aren't termdock's. */
+const TERMDOCK_ENV_MARKER = 'TERMDOCK';
+/** Env var Grok Build's hook runner injects into every hook process it spawns.
+ *  Its presence identifies *who ran us* — grok also scans ~/.claude/settings.json
+ *  for hooks (its Claude-compat layer), so a termdock Claude Code integration
+ *  also fires inside grok panes and must be relabeled to the agent that
+ *  actually ran it. */
+const GROK_HOOK_ENV = 'GROK_HOOK_EVENT';
+/** Cap on how much hook stdin we'll read: real payloads are a few hundred
+ *  bytes of JSON; anything huge is not for us. */
+const MAX_STDIN = 64 * 1024;
+/**
+ * The sentinel event one hook invocation maps onto, or null to stay silent.
+ * Most hooks pass their event through; the exceptions are the single catch-all
+ * `notification` hook Copilot and Grok expose, which fires for *every*
+ * notification type. Only the types that always mean a real block escalate to
+ * `permission-request`; everything else is dropped rather than parroted.
+ *
+ * The two agents draw that line differently. Copilot's `permission_prompt`
+ * only fires when it is actually asking, so it counts; grok dispatches the
+ * same type *before* its permission system decides — on essentially every tool
+ * call, auto-approved ones included — so only `elicitation_dialog` (grok
+ * asking the user a question) survives there.
+ */
+function effectiveEvent(agent, event, stdinJson) {
+    if ((agent === 'copilot' || agent === 'grok') && event === 'notification') {
+        const blocks = stdinJson.includes('elicitation_dialog')
+            || (agent === 'copilot' && stdinJson.includes('permission_prompt'));
+        return blocks ? 'permission-request' : null;
+    }
+    return event;
+}
+/** Write raw bytes to a tty device, best-effort. */
+function writeDev(path, bytes) {
+    try {
+        const fd = fs.openSync(path, 'w');
+        try {
+            fs.writeSync(fd, bytes);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The controlling-tty device of the nearest ancestor that has one — the agent
+ * process, when it ran us detached. Claude Code runs hooks *detached* from
+ * the controlling terminal (they have no /dev/tty), but the agent process
+ * itself still owns the pane's PTY slave. Walk up the parent chain via `ps`
+ * (the hook runs at most a few times per turn, so the spawn is negligible).
+ */
+function ancestorTtyDevice() {
+    let pid = process.ppid;
+    for (let i = 0; i < 8 && pid > 1; i++) {
+        let tty = '';
+        let ppid = 1;
+        try {
+            const out = execFileSync('ps', ['-o', 'tty=', '-o', 'ppid=', '-p', String(pid)], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: 2000,
+            });
+            const fields = out.trim().split(/\s+/);
+            tty = fields[0] ?? '';
+            ppid = parseInt(fields[1] ?? '1', 10) || 1;
+        }
+        catch {
+            return null;
+        }
+        if (tty && tty !== '??' && tty !== '?') {
+            return `/dev/${tty}`;
+        }
+        pid = ppid;
+    }
+    return null;
+}
+/**
+ * Write the sequence to the pane's PTY so the server sniffs it as pane output.
+ * Two routes: /dev/tty (hook attached to its tty), or an ancestor's tty
+ * device (agent ran us detached — write its PTY slave directly; writing the
+ * slave sends output to the master, exactly like /dev/tty would).
+ *
+ * Inside tmux the pane's tty is tmux's own PTY slave: a bare OSC would be
+ * consumed by tmux and never reach the attached client. When $TMUX is set we
+ * wrap the sequence in a DCS passthrough, which tmux (with allow-passthrough
+ * enabled, as termdock sets on managed sessions) forwards to its client —
+ * the termdock server — as the plain inner OSC.
+ */
+function writeToControllingTty(sequence, inTmuxPane) {
+    // Only genuine tmux panes (TMUX_PANE is set by tmux itself) get the DCS
+    // passthrough wrap; a bare inherited TMUX just means an ancestor ran tmux.
+    const wire = inTmuxPane
+        ? `\x1bPtmux;${sequence.replace(/\x1b/g, '\x1b\x1b')}\x1b\\`
+        : sequence;
+    if (writeDev('/dev/tty', wire))
+        return true;
+    const dev = ancestorTtyDevice();
+    if (dev)
+        return writeDev(dev, wire);
+    return false;
+}
+function main() {
+    try {
+        // Gate: emit when (a) inside a termdock-spawned shell (TERMDOCK env), or
+        // (b) inside any tmux pane (TMUX+TMUX_PANE) — there the passthrough wrap
+        // self-gates: sessions without allow-passthrough (anything termdock
+        // doesn't manage) swallow the sequence harmlessly. Anything else: stay
+        // silent, so globally-installed hooks don't leak into other terminals.
+        const inTmuxPane = !!(process.env.TMUX && process.env.TMUX_PANE);
+        if (!process.env[TERMDOCK_ENV_MARKER] && !inTmuxPane)
+            return;
+        // Command line: `agentHook.js agent-hook <agent> <event>` — the literal
+        // `agent-hook <slug>` token doubles as the installer's ownership marker.
+        const args = process.argv.slice(2);
+        if (args[0] === 'agent-hook')
+            args.shift();
+        let agent = args[0] ?? '';
+        const eventArg = args[1] ?? '';
+        if (!agent || !eventArg)
+            return;
+        if (process.env[GROK_HOOK_ENV])
+            agent = 'grok';
+        // Hook payload: the agent writes JSON and closes stdin. Absent/malformed
+        // input still emits the bare event — the state machine works without ids
+        // or messages. A tty stdin means the spawner inherited the pane's terminal
+        // instead of piping a payload; reading it would block forever on an EOF
+        // that never comes and swallow the user's keystrokes, so skip it.
+        let input = '';
+        if (!process.stdin.isTTY) {
+            try {
+                input = fs.readFileSync(0, 'utf8').slice(0, MAX_STDIN);
+            }
+            catch { /* no payload */ }
+        }
+        const event = effectiveEvent(agent, eventArg, input);
+        if (!event)
+            return;
+        writeToControllingTty(buildHookSequence(agent, event, input), inTmuxPane);
+    }
+    catch {
+        // Never break the agent's flow.
+    }
+    process.exit(0);
+}
+main();