@prohost/cli 0.13.3 → 0.14.0

package/dist/codehost/hooks.js

@@ -0,0 +1,726 @@
+/**
+ * Claude Code hooks and Codex `notify` for Mac-hosted Code threads.
+ *
+ * **Nothing global is installed.** The operator's `~/.claude/settings.json`
+ * and `~/.codex/config.toml` are never edited. Each thread's agent is launched
+ * with the hooks on its own command line — `claude --settings <file>`, `codex -c
+ * notify=[...]` — so they exist only in the sessions this host starts, and the
+ * one command they run is a shim that exits at once unless
+ * `$PROHOST_TERMINAL_ID` is set. A `claude` the operator starts in their own
+ * terminal sees none of it.
+ *
+ * The shim (`$PROHOST_HOME/code-host/bin/prohost-hook`) is rewritten on every
+ * daemon start to name the CLI that is installed now, so a session started
+ * under an older CLI (npx caches move) keeps working after an upgrade.
+ *
+ * What each hook reports (contract "Hook / host ingest"):
+ *
+ * | Hook | Event |
+ * | --- | --- |
+ * | `UserPromptSubmit` | `prompt {text}` |
+ * | `Stop` | `stop {finalText, question}` then `stats {...}` |
+ * | `PermissionRequest --wait <s>` | `permission_request {approvalId, command, options, capabilities: ['hook_decision'], waitMs, deadlineMs, sentAtMs}`, then waits for the decision and prints it (`decision.ts`); `prompt_local` if its wait runs out |
+ * | `PermissionRequest` (a window launched before `--wait`) | `permission_request`, then at once `prompt_local {reason: 'launched_before_update'}`: its Claude Code would kill a waiting hook at 10 s |
+ * | `Notification` (`permission_prompt`) | for a Claude Code without `PermissionRequest`: `permission_request`, then `prompt_local {reason: 'no_hook'}` |
+ * | `SessionStart` | nothing posted; like every hook, it marks the window past the trust dialog (`ready.ts`) |
+ * | Codex `agent-turn-complete` | `prompt` (when it carries one) then `stop` |
+ *
+ * `question` is always true for an interactive turn: when an interactive agent
+ * stops, its turn is over and nothing more happens until a person types — that
+ * is a hand-off by construction, not a reading of what it said.
+ *
+ * Ordinary hooks print nothing (a `UserPromptSubmit` hook's stdout becomes part of the
+ * prompt), except a waiting `PermissionRequest` hook's decision from ProhostAI,
+ * which never blocks the menu (Claude Code draws it while the hook runs, and
+ * applies whichever answers first). The verified modern profile also records
+ * PreToolUse IDs; recording failures block the tool rather than returning success. Claude Code and
+ * Codex credentials are never read; the only Claude file read is the session's
+ * own transcript, for the turn's final text and token counts, and for whether a
+ * held prompt's call is over (`decision.ts`).
+ */
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { chmodSync, closeSync, fstatSync, openSync, readSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { shellQuote } from '../agent/shell.js';
+import { markTurn } from './activity.js';
+import { event, EVENT_POST_TIMEOUT_MS, postCodeThreadEvent, readHookConfig } from './events.js';
+import { awaitSettlement, beatenDeny, markTurnAnswered, recentPrompt, registerWaiter, settle, toolFingerprint } from './decision.js';
+import { INVOCATION_PROTOCOL_ENV, permissionInvocationIds, recordInvocation, supportsInvocationProtocol } from './invocations.js';
+import { markReady, readyPath } from './ready.js';
+import { codeHostDir, ensurePrivateDir, loadSettings, writePrivateJson } from './settings.js';
+import { isValidId } from './tmux.js';
+export const TERMINAL_ID_ENV = 'PROHOST_TERMINAL_ID';
+export const CODE_THREAD_ID_ENV = 'PROHOST_CODE_THREAD_ID';
+/** Claude Code hook events this host registers. */
+export const CLAUDE_HOOK_EVENTS = [
+    'SessionStart',
+    'UserPromptSubmit',
+    'Stop',
+    'PermissionRequest',
+    'Notification',
+];
+export const APPROVAL_OPTIONS = ['allow', 'allow_session', 'deny'];
+/**
+ * Declared on a `permission_request` whose decision the hook itself returns
+ * (`decision.ts`): the server may relay a decision the moment it has the
+ * prompt, since it can only ever answer that prompt.
+ */
+export const HOOK_DECISION_CAPABILITY = 'hook_decision';
+/** Waits between `permission_request` attempts whose outcome is unknown, within the hook's wait. */
+export const POST_RETRY_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];
+/** Waits between `approval_overridden_locally` attempts, all within {@link OVERRIDE_BUDGET_MS}. */
+export const OVERRIDE_RETRY_DELAYS_MS = [500, 1_000, 2_000];
+/** Every correction attempt ends this soon after the PostToolUse hook started, under its 10 s timeout. */
+export const OVERRIDE_BUDGET_MS = 8_000;
+/** An attempt is only started with at least this much of the budget left. */
+const OVERRIDE_MIN_ATTEMPT_MS = 500;
+/**
+ * How long the `PermissionRequest` hook waits for a decision from ProhostAI.
+ * The menu is up in the terminal all along (Claude Code draws it while the hook
+ * runs), so the person at the Mac is never kept waiting by it: this bounds only
+ * how long a decision from ProhostAI may still answer the prompt.
+ */
+export const HOOK_DECISION_WAIT_S = 120;
+/** The hook's own timeout, past which Claude Code kills it: above its wait. */
+export const PERMISSION_HOOK_TIMEOUT_S = 150;
+/**
+ * A POST outcome that settles it: an answer the server would give again. A
+ * network failure or timeout (0), 408, 429 or a 5xx may not have landed, or
+ * may have landed with its answer lost, and is worth sending again (ingest
+ * is idempotent per `approvalId`).
+ */
+const settled = (status) => status >= 200 && status < 500 && status !== 408 && status !== 429;
+const MAX_PROMPT_CHARS = 8_000;
+const MAX_FINAL_TEXT_CHARS = 8_000;
+const MAX_COMMAND_CHARS = 500;
+export const MAX_PREVIEW_CHARS = 280;
+/** Only the end of a transcript is read: the last turn is all we want. */
+const TRANSCRIPT_TAIL_BYTES = 512 * 1024;
+/** A `permission_prompt` notification this soon after a `PermissionRequest` is the same prompt. */
+const PERMISSION_DEDUP_MS = 30_000;
+export function hookBinDir(env = process.env) {
+    return path.join(codeHostDir(env), 'bin');
+}
+export function hookShimPath(env = process.env) {
+    return path.join(hookBinDir(env), 'prohost-hook');
+}
+export function claudeSettingsPath(env = process.env) {
+    return path.join(codeHostDir(env), 'claude-settings.json');
+}
+/** The shim script: env-guarded, then the current CLI's `hook` command. */
+export function hookShimScript(nodePath, cliEntrypoint) {
+    const q = (value) => shellQuote(value, 'darwin');
+    return [
+        '#!/bin/sh',
+        '# Written by `prohost agent run` on every start; it names the CLI installed now.',
+        '# Runs only inside a Code-thread terminal this machine hosts.',
+        `[ -n "$${TERMINAL_ID_ENV}" ] || exit 0`,
+        `[ -n "$${CODE_THREAD_ID_ENV}" ] || exit 0`,
+        // The pane's env has no `ELECTRON_RUN_AS_NODE` (`paneEnv`): set here, for this process only, so
+        // a CLI the desktop app runs on its Electron binary still runs the hook as Node. Node ignores it.
+        `ELECTRON_RUN_AS_NODE=1 exec ${q(nodePath)} ${q(cliEntrypoint)} hook "$@"`,
+        '',
+    ].join('\n');
+}
+/** The `--settings` document Claude Code is launched with: hooks only. */
+export function claudeHookSettings(shimPath, invocationProtocol = false) {
+    const hooks = {};
+    for (const name of CLAUDE_HOOK_EVENTS) {
+        // The PermissionRequest hook waits for a decision from ProhostAI (`--wait`), within its own
+        // timeout: past it Claude Code would kill the hook mid-wait.
+        const waits = name === 'PermissionRequest';
+        hooks[name] = [
+            {
+                hooks: [
+                    {
+                        type: 'command',
+                        command: `${shellQuote(shimPath, 'darwin')} claude ${name}${waits ? ` --wait ${HOOK_DECISION_WAIT_S}` : ''}`,
+                        timeout: waits ? PERMISSION_HOOK_TIMEOUT_S : 10,
+                        ...(invocationProtocol && waits ? { onFailure: 'block' } : {}),
+                    },
+                ],
+            },
+        ];
+    }
+    if (invocationProtocol)
+        hooks.PreToolUse = [{ hooks: [{
+                        type: 'command', command: `${shellQuote(shimPath, 'darwin')} claude PreToolUse`,
+                        timeout: 10, onFailure: 'block',
+                    }] }];
+    // The tool ran: reports a deny from ProhostAI that a "Yes" in the terminal beat (`beatenDeny`, by
+    // the exact invocation ids PreToolUse recorded). Reporting only, never blocking.
+    if (invocationProtocol)
+        hooks.PostToolUse = [{ hooks: [{
+                        type: 'command', command: `${shellQuote(shimPath, 'darwin')} claude PostToolUse`, timeout: 10,
+                    }] }];
+    return { hooks };
+}
+/** Codex `-c notify=[...]` value (TOML array), naming the shim. */
+export function codexNotifyOverride(shimPath) {
+    return `notify=${JSON.stringify([shimPath, 'codex'])}`;
+}
+/** Write the shim and Claude settings. Called on every daemon start. */
+export function installHookFiles(nodePath, cliEntrypoint, env = process.env) {
+    const shim = hookShimPath(env);
+    ensurePrivateDir(path.dirname(shim));
+    // A temp file and a rename: a hook running right now never reads half a script.
+    const temp = `${shim}.${process.pid}.tmp`;
+    writeFileSync(temp, hookShimScript(nodePath, cliEntrypoint), { mode: 0o700 });
+    chmodSync(temp, 0o700);
+    renameSync(temp, shim);
+    const claudeSettings = claudeSettingsPath(env);
+    writePrivateJson(claudeSettings, claudeHookSettings(shim));
+    const claudeInvocationSettings = path.join(codeHostDir(env), 'claude-invocation-settings.json');
+    writePrivateJson(claudeInvocationSettings, claudeHookSettings(shim, true));
+    return { shim, claudeSettings, claudeInvocationSettings };
+}
+// ── Parsing what the agents hand their hooks ───────────────────────────────
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function str(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function clip(text, max) {
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+/** Last non-empty line, clipped — the inbox row's preview. */
+export function previewOf(text) {
+    const lines = text.split('\n').map((line) => line.trim()).filter(Boolean);
+    const last = lines[lines.length - 1];
+    return last ? clip(last, MAX_PREVIEW_CHARS) : undefined;
+}
+/**
+ * The last assistant turn of a Claude Code transcript (JSONL): its text and
+ * token usage. Unknown shapes yield nothing rather than zeros.
+ */
+export function parseTranscriptTail(content) {
+    const lines = content.split('\n');
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = lines[i].trim();
+        if (!line.startsWith('{'))
+            continue;
+        let entry;
+        try {
+            entry = asObject(JSON.parse(line));
+        }
+        catch {
+            continue;
+        }
+        if (!entry || entry.type !== 'assistant')
+            continue;
+        const message = asObject(entry.message);
+        const content = Array.isArray(message?.content) ? message.content : [];
+        const text = content
+            .map((part) => asObject(part))
+            .filter((part) => part?.type === 'text' && typeof part.text === 'string')
+            .map((part) => part.text)
+            .join('\n')
+            .trim();
+        if (!text)
+            continue;
+        const turn = { finalText: text };
+        const usage = asObject(message?.usage);
+        const n = (key) => {
+            const value = usage?.[key];
+            return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+        };
+        const input = n('input_tokens');
+        const output = n('output_tokens');
+        const created = n('cache_creation_input_tokens') ?? 0;
+        const read = n('cache_read_input_tokens') ?? 0;
+        if (input !== undefined && output !== undefined) {
+            turn.tokensTotal = input + created + read + output;
+            const prompt = input + created + read;
+            if (prompt > 0)
+                turn.tokensCachedPct = Math.round((read / prompt) * 1000) / 10;
+        }
+        return turn;
+    }
+    return {};
+}
+function readTail(file, bytes = TRANSCRIPT_TAIL_BYTES) {
+    let fd;
+    try {
+        fd = openSync(file, 'r');
+        const size = fstatSync(fd).size;
+        const length = Math.min(size, bytes);
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, size - length);
+        return buffer.toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** `git diff --shortstat` numbers for a worktree, against where its branch left the default branch. */
+export function parseShortstat(text) {
+    const num = (re) => Number.parseInt(re.exec(text)?.[1] ?? '0', 10);
+    return {
+        filesChanged: num(/(\d+) files? changed/),
+        additions: num(/(\d+) insertions?\(\+\)/),
+        deletions: num(/(\d+) deletions?\(-\)/),
+    };
+}
+const defaultGit = (args, cwd) => new Promise((resolve) => {
+    execFile('git', ['-C', cwd, ...args], { timeout: 3_000, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+        resolve(error ? undefined : String(stdout));
+    });
+});
+/** Untracked files counted, and the bytes of each read for its lines; past these they count as one file, no lines. */
+const MAX_UNTRACKED_FILES = 500;
+const MAX_UNTRACKED_BYTES = 1024 * 1024;
+/** Lines in a new file as `git diff` would count them added: none for a binary one. */
+function linesIn(file) {
+    let fd;
+    try {
+        fd = openSync(file, 'r');
+        const size = fstatSync(fd).size;
+        if (size === 0 || size > MAX_UNTRACKED_BYTES)
+            return 0;
+        const buffer = Buffer.alloc(size);
+        readSync(fd, buffer, 0, size, 0);
+        if (buffer.includes(0))
+            return 0;
+        let lines = 0;
+        for (const byte of buffer)
+            if (byte === 0x0a)
+                lines += 1;
+        return buffer[size - 1] === 0x0a ? lines : lines + 1;
+    }
+    catch {
+        return 0;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/**
+ * What the thread changed in its worktree, against where its branch left the
+ * default branch: commits, uncommitted edits, and new files not yet added
+ * (`git diff` alone never counts an untracked file, so a thread that made one
+ * would read "No changes yet").
+ */
+export async function diffStats(cwd, git = defaultGit, countLines = linesIn) {
+    let base;
+    for (const ref of ['origin/HEAD', 'origin/main', 'origin/master']) {
+        base = (await git(['merge-base', 'HEAD', ref], cwd))?.trim();
+        if (base)
+            break;
+    }
+    const out = await git(['diff', '--shortstat', base || 'HEAD'], cwd);
+    if (out === undefined)
+        return undefined;
+    const stats = parseShortstat(out);
+    const untracked = (await git(['ls-files', '--others', '--exclude-standard', '-z'], cwd))?.split('\0').filter(Boolean) ?? [];
+    untracked.forEach((file, index) => {
+        stats.filesChanged += 1;
+        if (index < MAX_UNTRACKED_FILES)
+            stats.additions += countLines(path.join(cwd, file));
+    });
+    return stats;
+}
+/** Stable approval id for one permission prompt, so a retried hook doesn't make two. */
+export function approvalIdFor(parts) {
+    const material = parts.filter(Boolean).join('\u0000');
+    if (!material)
+        return randomUUID();
+    return createHash('sha256').update(material).digest('hex').slice(0, 32);
+}
+/** A one-line description of what a tool wants to do. */
+export function permissionCommand(toolName, toolInput) {
+    const input = asObject(toolInput) ?? {};
+    const command = str(input.command);
+    if (command)
+        return clip(command, MAX_COMMAND_CHARS);
+    const target = str(input.file_path) ?? str(input.path) ?? str(input.url) ?? '';
+    return clip(`${toolName ?? 'Tool'} ${target}`.trim(), MAX_COMMAND_CHARS);
+}
+/** Events for one Claude Code hook invocation. Pure apart from the context's readers. */
+export async function claudeHookEvents(hook, input, ctx) {
+    const now = ctx.now();
+    const terminalId = ctx.env[TERMINAL_ID_ENV] ?? '';
+    const hasTerminal = isValidId(terminalId);
+    // PermissionRequest has no invocation ID. A matching per-tool hook may belong
+    // to an unregistered call, so only turn/user progress can retire these guards.
+    const turnProgress = () => {
+        if (!hasTerminal)
+            return;
+        try {
+            markTurnAnswered(terminalId, ctx.env, ctx.now);
+        }
+        catch {
+            // Unreadable state keeps replies guarded.
+        }
+    };
+    if (hook === 'PostToolUse') {
+        // Retires nothing: an identical call that needed no prompt reaches here too.
+        if (!hasTerminal)
+            return [];
+        try {
+            const approvalId = beatenDeny(terminalId, input.tool_use_id, input.tool_name, input.tool_input, ctx.env);
+            return approvalId ? [event('approval_overridden_locally', { approvalId, outcome: 'allowed' }, now)] : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    if (hook === 'UserPromptSubmit') {
+        turnProgress();
+        const text = str(input.prompt);
+        return text ? [event('prompt', { text: clip(text, MAX_PROMPT_CHARS) }, now)] : [];
+    }
+    if (hook === 'Stop') {
+        turnProgress();
+        const transcript = str(input.transcript_path);
+        const turn = transcript ? parseTranscriptTail(ctx.readTranscript(transcript) ?? '') : {};
+        const finalText = str(input.last_assistant_message) ?? turn.finalText ?? '';
+        const events = [event('stop', { finalText: clip(finalText, MAX_FINAL_TEXT_CHARS), question: true }, now)];
+        const cwd = str(input.cwd);
+        const diff = cwd ? await diffStats(cwd, ctx.git) : undefined;
+        const stats = {};
+        if (turn.tokensTotal !== undefined)
+            stats.tokensTotal = turn.tokensTotal;
+        if (turn.tokensCachedPct !== undefined)
+            stats.tokensCachedPct = turn.tokensCachedPct;
+        if (diff)
+            Object.assign(stats, diff);
+        const preview = previewOf(finalText);
+        if (preview)
+            stats.preview = preview;
+        if (Object.keys(stats).length > 0)
+            events.push(event('stats', stats, now));
+        return events;
+    }
+    if (hook === 'Notification') {
+        if (str(input.notification_type) !== 'permission_prompt')
+            return [];
+        // A Claude Code with the PermissionRequest hook has already reported this prompt (its hook
+        // is waiting on it, or settled it a moment ago).
+        if (hasTerminal && recentPrompt(terminalId, ctx.env, now, PERMISSION_DEDUP_MS))
+            return [];
+        // A Claude Code without it: nothing here can return a decision, so the prompt is the terminal's.
+        const message = clip(str(input.message) ?? 'Permission needed', MAX_COMMAND_CHARS);
+        const approvalId = approvalIdFor([str(input.session_id), message, String(Math.floor(now / PERMISSION_DEDUP_MS))]);
+        return [
+            event('permission_request', { approvalId, command: message, options: [...APPROVAL_OPTIONS] }, now),
+            event('prompt_local', { approvalId, reason: 'no_hook' }, now),
+        ];
+    }
+    return [];
+}
+/** Events for one Codex `notify` call; `payload` is the JSON Codex passes as the last argument. */
+export function codexNotifyEvents(payload, now) {
+    let data;
+    try {
+        data = asObject(JSON.parse(payload));
+    }
+    catch {
+        return [];
+    }
+    if (!data || data.type !== 'agent-turn-complete')
+        return [];
+    const events = [];
+    const inputs = Array.isArray(data['input-messages']) ? data['input-messages'] : [];
+    const prompt = inputs.filter((m) => typeof m === 'string').join('\n').trim();
+    if (prompt)
+        events.push(event('prompt', { text: clip(prompt, MAX_PROMPT_CHARS) }, now));
+    const finalText = str(data['last-assistant-message']) ?? '';
+    events.push(event('stop', { finalText: clip(finalText, MAX_FINAL_TEXT_CHARS), question: true }, now));
+    const preview = previewOf(finalText);
+    if (preview)
+        events.push(event('stats', { preview }, now));
+    return events;
+}
+async function readStdin(stream, limit = 4 * 1024 * 1024) {
+    if (stream.isTTY)
+        return '';
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += buffer.length;
+        if (size > limit)
+            break;
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * One hook can report several events at the moment it fired (`stop` then
+ * `stats`). Ingest drops an event older than the newest it applied for the
+ * thread, so each later event gets a later `at` — a millisecond apart.
+ */
+export function strictlyIncreasing(events) {
+    let last = -Infinity;
+    return events.map((body) => {
+        const at = Math.max(Date.parse(body.at), last + 1);
+        last = at;
+        return { ...body, at: new Date(at).toISOString() };
+    });
+}
+/** Claude Code stops a hook with a signal (Escape, or "No" in the menu): settle, then exit quietly. */
+const onStopSignals = (handler) => {
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
+        process.once(signal, () => {
+            try {
+                handler();
+            }
+            finally {
+                process.exit(0);
+            }
+        });
+    }
+};
+// ── A decision answered by the hook (`decision.ts`) ────────────────────────
+/** `--wait <seconds>` on the hook's command line, capped below its timeout; 0 without one. */
+export function waitArg(args) {
+    const at = args.indexOf('--wait');
+    const seconds = at >= 0 ? Number(args[at + 1]) : 0;
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return 0;
+    return Math.min(seconds, PERMISSION_HOOK_TIMEOUT_S - 10) * 1000;
+}
+/**
+ * "Allow for this session", as Claude Code offers it for this prompt: its first
+ * suggestion that adds an allow rule, kept to the session. Only that kind: a
+ * suggestion to add a directory or switch mode grants more than the one call
+ * the person decided on. None: the option isn't offered.
+ */
+export function sessionRule(suggestions) {
+    if (!Array.isArray(suggestions))
+        return undefined;
+    for (const raw of suggestions) {
+        const suggestion = asObject(raw);
+        if (suggestion?.type !== 'addRules' || suggestion.behavior !== 'allow' || !Array.isArray(suggestion.rules))
+            continue;
+        return { type: 'addRules', rules: suggestion.rules, behavior: 'allow', destination: 'session' };
+    }
+    return undefined;
+}
+/** The hook's stdout for a decision: what Claude Code applies to the prompt. */
+export function decisionOutput(decision, rule) {
+    const body = decision === 'deny'
+        ? { behavior: 'deny', message: 'Denied in ProhostAI.' }
+        : decision === 'allow_session' && rule
+            ? { behavior: 'allow', updatedPermissions: [rule] }
+            : { behavior: 'allow' };
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: 'PermissionRequest', decision: body } });
+}
+/**
+ * The `PermissionRequest` hook, waiting: report the prompt, then wait for its
+ * settlement and print ProhostAI's decision if that is what settled it. Any
+ * other ending prints nothing, so the menu in the terminal decides; when the
+ * wait simply ran out, the server is told the prompt is the terminal's now.
+ */
+async function answerPermissionRequest(input, ctx, codeThreadId, wait, options) {
+    const { env } = ctx;
+    const terminalId = env[TERMINAL_ID_ENV] ?? '';
+    const start = ctx.now();
+    const toolName = str(input.tool_name);
+    const command = permissionCommand(toolName, input.tool_input);
+    // One hook run is one prompt: two identical calls in a session are two prompts.
+    const approvalId = approvalIdFor([str(input.session_id), toolName, command, String(start), String(process.pid), randomUUID()]);
+    const rule = sessionRule(input.permission_suggestions);
+    const deadline = start + wait.waitMs;
+    // `deadlineMs` and `sentAtMs` are this Mac's clock: the server reads how long is left
+    // (`deadlineMs - sentAtMs`, at the attempt it took) against its own, so a request that took
+    // a few attempts never looks as though its hook waits longer than it does.
+    const request = () => event('permission_request', {
+        approvalId,
+        command,
+        options: rule ? [...APPROVAL_OPTIONS] : ['allow', 'deny'],
+        capabilities: [HOOK_DECISION_CAPABILITY],
+        waitMs: wait.waitMs,
+        deadlineMs: deadline,
+        sentAtMs: ctx.now(),
+    }, start);
+    const initialRequest = request();
+    try {
+        const causal = env[INVOCATION_PROTOCOL_ENV] === '1' && input.agent_id === undefined;
+        const toolUseIds = causal ? permissionInvocationIds(terminalId, input, env) : undefined;
+        const transcript = causal ? str(input.transcript_path) : undefined;
+        registerWaiter(terminalId, {
+            approvalId,
+            pid: process.pid,
+            deadline,
+            fingerprint: toolFingerprint(toolName, input.tool_input),
+            permissionRequest: initialRequest,
+            // Where Claude Code records this call's end, for a menu no hook will report gone.
+            ...(transcript && toolUseIds ? { transcript, toolUseIds } : {}),
+        }, env);
+    }
+    catch {
+        if (env[INVOCATION_PROTOCOL_ENV] === '1') {
+            process.stderr.write('prohost: permission invocation could not be recorded; refusing the request\n');
+            return 1; // The modern profile's onFailure:block denies this request.
+        }
+        return 0; // nowhere to wait: the terminal answers it
+    }
+    wait.onStop(() => settle(terminalId, approvalId, { by: 'cancelled', at: ctx.now() }, env));
+    const post = async (body) => {
+        const config = readHookConfig(env, ctx.now());
+        return config ? postCodeThreadEvent(config, codeThreadId, body, options.fetchImpl) : 0;
+    };
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    // Sent until it settles (ingest is idempotent per approvalId), within the wait.
+    let status = await post(initialRequest);
+    for (const delay of POST_RETRY_DELAYS_MS) {
+        if (settled(status) || ctx.now() + delay >= deadline)
+            break;
+        await sleep(delay);
+        status = await post(request());
+    }
+    const stored = status >= 200 && status < 300;
+    // Not known to be stored: stop waiting. Only the answers may have been lost, so a decision can
+    // already stand, and the server may still be offering a prompt nothing here waits on.
+    const settlement = stored
+        ? await awaitSettlement(terminalId, approvalId, deadline, env, ctx.now, sleep)
+        : settle(terminalId, approvalId, { by: 'timeout', at: ctx.now() }, env).settlement;
+    if (settlement?.by === 'host') {
+        wait.stdout(decisionOutput(settlement.decision, rule));
+        return 0;
+    }
+    // A request the server refused outright has no prompt there to correct.
+    const refused = settled(status) && !stored;
+    if (settlement?.by === 'timeout' && !refused) {
+        const reason = wait.waitMs > 0 ? 'timeout' : wait.localReason;
+        await post(event('prompt_local', { approvalId, reason }, Math.max(ctx.now(), start + 1)));
+    }
+    return 0;
+}
+/**
+ * `prohost hook claude <Event>` / `prohost hook codex <payload>`. Critical invocation
+ * recording failures are nonzero; ordinary reporting failures stay nonblocking.
+ */
+export async function runHook(args, options = {}) {
+    const env = options.env ?? process.env;
+    const codeThreadId = env[CODE_THREAD_ID_ENV];
+    const [kind, name] = args;
+    const preflight = kind === 'claude' && name === 'CheckInvocationProtocol';
+    const critical = kind === 'claude' && name === 'PreToolUse';
+    if (!isValidId(env[TERMINAL_ID_ENV]) || !isValidId(codeThreadId))
+        return critical ? 2 : preflight ? 1 : 0;
+    if (preflight) {
+        try {
+            const version = await (options.claudeVersion ?? (() => new Promise((resolve) => {
+                execFile('claude', ['--version'], { env, timeout: 3_000, maxBuffer: 64 * 1024 }, (error, stdout) => {
+                    resolve(error ? undefined : String(stdout));
+                });
+            })))();
+            if (supportsInvocationProtocol(version))
+                return 0;
+            process.stderr.write('prohost: immediate reply recovery requires Claude Code 2.1.295+. After Escape, this session may wait for a new prompt or completed turn.\n');
+            return 1;
+        }
+        catch {
+            return 1;
+        }
+    }
+    if (critical) {
+        try {
+            if (env[INVOCATION_PROTOCOL_ENV] !== '1')
+                throw new Error('Unsupported invocation protocol');
+            const input = asObject(JSON.parse(await readStdin(options.stdin ?? process.stdin)));
+            if (!input)
+                throw new Error('Invalid invocation input');
+            recordInvocation(env[TERMINAL_ID_ENV], input, env);
+            markReady(env[TERMINAL_ID_ENV], env);
+            return 0;
+        }
+        catch {
+            process.stderr.write('prohost: tool invocation could not be recorded; blocking the tool call\n');
+            return 2;
+        }
+    }
+    const now = options.now ?? Date.now;
+    const config = readHookConfig(env, now());
+    const ctx = {
+        env,
+        now,
+        git: options.git ?? defaultGit,
+        readTranscript: (file) => readTail(file),
+    };
+    let events = [];
+    try {
+        if (kind === 'claude' && name) {
+            // A hook runs only once the folder is trusted: from here a relayed reply may be typed (`ready.ts`).
+            // Only a valid terminal id names a path (no `..` from a hook's environment reaches the state dir).
+            const terminalId = env[TERMINAL_ID_ENV];
+            if (isValidId(terminalId) && !markReady(terminalId, env)) {
+                // Said where an operator looks (Claude Code shows hook stderr in its verbose log), never swallowed.
+                process.stderr.write(`prohost: could not write ${readyPath(terminalId, env)}; replies from ProhostAI can't be typed into this terminal\n`);
+            }
+            // Keep-awake (`activity.ts`): a turn runs from its prompt to Claude Code's stop. Marked first,
+            // before stdin and the Stop hook's transcript and git work, which may outlast its timeout.
+            if (name === 'UserPromptSubmit' || name === 'Stop')
+                markTurn(terminalId, name === 'UserPromptSubmit', env);
+            const raw = await readStdin(options.stdin ?? process.stdin);
+            let input = {};
+            try {
+                input = asObject(JSON.parse(raw)) ?? {};
+            }
+            catch {
+                input = {};
+            }
+            if (name === 'PermissionRequest') {
+                // This host's settings ask the hook to wait for a decision (`--wait`). It waits only while
+                // the owner allows remote control. A window launched before that (no `--wait`) keeps a
+                // Claude Code that kills its hooks at 10 s: its prompts are the terminal's.
+                const waitMs = waitArg(args);
+                const remote = loadSettings(env).allowRemoteTerminal;
+                return await answerPermissionRequest(input, ctx, codeThreadId, {
+                    waitMs: remote ? waitMs : 0,
+                    localReason: waitMs === 0 ? 'launched_before_update' : 'remote_off',
+                    stdout: options.stdout ?? ((text) => void process.stdout.write(text)),
+                    onStop: options.onStop ?? onStopSignals,
+                }, options);
+            }
+            events = await claudeHookEvents(name, input, ctx);
+        }
+        else if (kind === 'codex') {
+            events = codexNotifyEvents(args[args.length - 1] ?? '', ctx.now());
+        }
+    }
+    catch {
+        if (kind === 'claude' && name === 'PermissionRequest' && env[INVOCATION_PROTOCOL_ENV] === '1') {
+            process.stderr.write('prohost: permission hook failed; refusing the request\n');
+            return 1;
+        }
+        return 0;
+    }
+    // Keep-awake (`activity.ts`): Codex says only when a turn ends; the host marks the turns it
+    // starts or types (`terminals.ts`). Claude Code's are marked above.
+    if (kind === 'codex' && events.some((body) => body.type === 'stop'))
+        markTurn(env[TERMINAL_ID_ENV], false, env);
+    if (!config)
+        return 0;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const started = now();
+    // Sequential, in order: ingest drops an event older than the newest it applied.
+    for (const body of strictlyIncreasing(events)) {
+        if (body.type !== 'approval_overridden_locally') {
+            await postCodeThreadEvent(config, codeThreadId, body, options.fetchImpl);
+            continue;
+        }
+        // A correction is said once (`beatenDeny` marks it reported): sent again while its answer may be
+        // lost or the server asks for it later (the deny's delivery busy, 503). Every attempt, waits
+        // included, ends within OVERRIDE_BUDGET_MS of the hook's start: Claude Code holds the tool's
+        // result for PostToolUse and kills it at 10 s.
+        const left = () => started + OVERRIDE_BUDGET_MS - now();
+        let status = await postCodeThreadEvent(config, codeThreadId, body, options.fetchImpl, Math.min(EVENT_POST_TIMEOUT_MS, left()));
+        for (const delay of OVERRIDE_RETRY_DELAYS_MS) {
+            if (settled(status) || left() - delay <= OVERRIDE_MIN_ATTEMPT_MS)
+                break;
+            await sleep(delay);
+            status = await postCodeThreadEvent(config, codeThreadId, body, options.fetchImpl, Math.min(EVENT_POST_TIMEOUT_MS, left()));
+        }
+    }
+    return 0;
+}