@prohost/cli 0.13.3 → 0.14.0

package/dist/codehost/decision.js

@@ -0,0 +1,553 @@
+/**
+ * A decision made in ProhostAI, answered by the agent's own `PermissionRequest`
+ * hook rather than by keys pressed into its pane.
+ *
+ * Claude Code draws its permission menu while that hook is still running, and
+ * applies whichever comes first: the hook's printed decision or an answer in
+ * the terminal (checked against 2.1.314). So the hook waits, bounded, for a
+ * decision for its own prompt, and a decision can never land on another one.
+ *
+ * Two files per prompt, in the private state dir, named by its `approvalId`:
+ *
+ * - `<terminal>.waiter-<id>.json`: the hook waiting on it (`pid`, `deadline`,
+ *   tool fingerprint). Fingerprints are diagnostic only: they do not establish
+ *   invocation identity or application.
+ * - `<terminal>.decision-<id>.json`: **the settlement**, created exactly once
+ *   (a temp file `link`ed into place, which never overwrites) by whoever
+ *   settles the prompt first:
+ *   - `host`: the decision from ProhostAI, which the waiting hook prints;
+ *   - `timeout`: the hook's wait ran out; the menu is answered in the terminal;
+ *   - `local`: turn/user progress retired the prompt;
+ *   - `cancelled`: the hook received a stop signal; not proof the menu closed.
+ *
+ * A host acknowledgement records handoff to a hook, not proof the parent
+ * applied it. PermissionRequest lacks invocation identity. A verified PreToolUse
+ * hook records the candidate IDs first; only their own transcript completions,
+ * a new user prompt or a completed turn release replies. Legacy per-tool
+ * receipts are not trusted.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, fstatSync, linkSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { forgetInvocations } from './invocations.js';
+import { codeHostDir, ensurePrivateDir, writePrivateJson } from './settings.js';
+import { isValidId } from './tmux.js';
+/** Approval ids as `permission_request` mints them (`approvalIdFor`). */
+const APPROVAL_ID = /^[A-Za-z0-9-]{1,64}$/;
+const DECISIONS = new Set(['allow', 'allow_session', 'deny']);
+function stateDir(env) {
+    return path.join(codeHostDir(env), 'state');
+}
+function checked(terminalId, approvalId) {
+    if (!isValidId(terminalId) || !APPROVAL_ID.test(approvalId))
+        throw new Error('invalid approval name');
+}
+export function waiterPath(terminalId, approvalId, env = process.env) {
+    checked(terminalId, approvalId);
+    return path.join(stateDir(env), `${terminalId}.waiter-${approvalId}.json`);
+}
+export function settlementPath(terminalId, approvalId, env = process.env) {
+    checked(terminalId, approvalId);
+    return path.join(stateDir(env), `${terminalId}.decision-${approvalId}.json`);
+}
+/** A tool call as `PermissionRequest` saw it. Not an invocation's identity: identical calls share it. */
+export function toolFingerprint(toolName, toolInput) {
+    return createHash('sha256')
+        .update(JSON.stringify([typeof toolName === 'string' ? toolName : '', toolInput ?? null]))
+        .digest('hex')
+        .slice(0, 32);
+}
+/**
+ * A transcript is read whole up to this bound, preserving complete ID/result evidence.
+ * Beyond it nothing is released; a later turn-progress hook still clears.
+ */
+const TRANSCRIPT_MAX_BYTES = 64 * 1024 * 1024;
+const transcriptCache = new Map();
+/** Verification reads the whole cached prefix with bounded temporary storage. */
+const TRANSCRIPT_HASH_CHUNK_BYTES = 64 * 1024;
+/** A finished session's transcript is forgotten once no prompt has asked about it for this long. */
+const TRANSCRIPT_CACHE_IDLE_MS = 30 * 60_000;
+/** The hash of every byte already read from `fd`, rather than a sampled window. */
+function prefixHash(fd, end) {
+    const hash = createHash('sha256');
+    const bytes = Buffer.alloc(Math.min(end, TRANSCRIPT_HASH_CHUNK_BYTES));
+    for (let offset = 0; offset < end;) {
+        const length = Math.min(bytes.length, end - offset);
+        const read = readSync(fd, bytes, 0, length, offset);
+        if (read === 0)
+            throw new Error('Transcript changed during verification');
+        hash.update(bytes.subarray(0, read));
+        offset += read;
+    }
+    return hash.digest('hex');
+}
+/** Drops every cached transcript no prompt has read for {@link TRANSCRIPT_CACHE_IDLE_MS}. */
+function pruneTranscripts(now) {
+    for (const [file, cache] of transcriptCache) {
+        if (now - cache.readAt > TRANSCRIPT_CACHE_IDLE_MS)
+            transcriptCache.delete(file);
+    }
+}
+/** Lines of a transcript parsed, ever: for tests that a second read parses only what was appended. */
+export const transcriptParseCounter = { lines: 0 };
+/** For tests: forget every transcript read so far. */
+export function forgetTranscriptsForTests() {
+    transcriptCache.clear();
+    transcriptParseCounter.lines = 0;
+}
+/**
+ * Adds one transcript line's calls and results to `record`. `false`: not a readable entry, which may
+ * have been a call, so every line is parsed: one cut short needn't say `tool_use` to have been one.
+ */
+function addTranscriptLine(record, line) {
+    if (line.trim() === '')
+        return true;
+    transcriptParseCounter.lines += 1;
+    let entry;
+    try {
+        entry = JSON.parse(line);
+    }
+    catch {
+        return false;
+    }
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+        return false;
+    const message = entry.message;
+    const content = Array.isArray(message?.content) ? message.content : [];
+    const at = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN;
+    if (!Number.isFinite(at)) {
+        // `api-request-blob`s are copies of what was sent, not a record of when. Any other call that can't
+        // be placed may be the held one.
+        return entry.type === 'api-request-blob' || !content.some((part) => part?.type === 'tool_use');
+    }
+    for (const part of content) {
+        if (part?.type === 'tool_use' && typeof part.id === 'string') {
+            record.uses.set(part.id, ++record.order);
+        }
+        else if (part?.type === 'tool_result' && typeof part.tool_use_id === 'string') {
+            record.results.set(part.tool_use_id, ++record.order);
+        }
+    }
+    return true;
+}
+/**
+ * Every call and result in the transcript at `file` (absolute, `.jsonl`), read whole the first time
+ * and then only as it grows. `undefined` (closed: nothing is released) when it can't be read, is
+ * larger than {@link TRANSCRIPT_MAX_BYTES}, has a complete line that isn't readable, or ends in a line
+ * still being written, which may be the held call's own.
+ */
+function readTranscriptRecord(file, now = Date.now()) {
+    if (!path.isAbsolute(file) || !file.endsWith('.jsonl'))
+        return undefined;
+    pruneTranscripts(now);
+    let fd;
+    try {
+        let stat;
+        try {
+            stat = statSync(file);
+        }
+        catch (err) {
+            // Gone (a finished session's transcript deleted), or unreadable: nothing of it is kept.
+            transcriptCache.delete(file);
+            throw err;
+        }
+        if (!stat.isFile() || stat.size > TRANSCRIPT_MAX_BYTES) {
+            transcriptCache.delete(file);
+            return undefined;
+        }
+        fd = openSync(file, 'r');
+        // Bind the snapshot to the opened file if the path was replaced after statSync.
+        stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > TRANSCRIPT_MAX_BYTES) {
+            transcriptCache.delete(file);
+            return undefined;
+        }
+        let cache = transcriptCache.get(file);
+        const rewritten = cache !== undefined &&
+            (cache.ino !== stat.ino ||
+                stat.size < cache.offset + cache.partial.length ||
+                prefixHash(fd, cache.size) !== cache.prefix.copy().digest('hex'));
+        if (!cache || rewritten) {
+            cache = {
+                ino: stat.ino,
+                size: 0,
+                mtimeMs: 0,
+                offset: 0,
+                partial: Buffer.alloc(0),
+                broken: false,
+                record: { uses: new Map(), results: new Map(), order: 0 },
+                prefix: createHash('sha256'),
+                readAt: now,
+            };
+            transcriptCache.set(file, cache);
+        }
+        cache.readAt = now;
+        if (stat.size !== cache.size || stat.mtimeMs !== cache.mtimeMs) {
+            const start = cache.offset + cache.partial.length;
+            const added = Buffer.alloc(stat.size - start);
+            for (let offset = 0; offset < added.length;) {
+                const read = readSync(fd, added, offset, added.length - offset, start + offset);
+                if (read === 0)
+                    throw new Error('Transcript changed during read');
+                offset += read;
+            }
+            const bytes = Buffer.concat([cache.partial, added]);
+            const end = bytes.lastIndexOf(0x0a) + 1;
+            for (const line of bytes.subarray(0, end).toString('utf8').split('\n')) {
+                if (!cache.broken && !addTranscriptLine(cache.record, line))
+                    cache.broken = true;
+            }
+            cache.offset += end;
+            cache.partial = Buffer.from(bytes.subarray(end));
+            cache.size = stat.size;
+            cache.mtimeMs = stat.mtimeMs;
+            // Hash the bytes used by the parser, not a second file read that could already be a rewrite.
+            cache.prefix.update(added);
+        }
+        // A rewrite may change an already-verified chunk while later chunks are being read.
+        const after = fstatSync(fd);
+        if (after.dev !== stat.dev || after.ino !== stat.ino || after.size !== stat.size ||
+            after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs) {
+            transcriptCache.delete(file);
+            return undefined;
+        }
+        return cache.broken || cache.partial.length > 0 ? undefined : cache.record;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** Every invocation that could own this permission must have its own subsequent result. */
+function callIsOver(record, ids) {
+    return ids.length > 0 && ids.every((id) => {
+        const use = record.uses.get(id);
+        const result = record.results.get(id);
+        return use !== undefined && result !== undefined && result > use;
+    });
+}
+/** Exact IDs, not content, counts or timestamp proximity, establish transcript completion. */
+export function transcriptReleases(transcript, ids, now = Date.now()) {
+    const record = readTranscriptRecord(transcript, now);
+    return record !== undefined && callIsOver(record, ids);
+}
+/** For tests: the transcripts the cache holds now. */
+export function cachedTranscriptsForTests() {
+    return [...transcriptCache.keys()];
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+function parseSettlement(text) {
+    try {
+        const value = JSON.parse(text);
+        const at = typeof value.at === 'number' ? value.at : 0;
+        if (value.by === 'host') {
+            return typeof value.decision === 'string' && DECISIONS.has(value.decision)
+                ? { by: 'host', decision: value.decision, at }
+                : undefined;
+        }
+        if (value.by === 'timeout' || value.by === 'local' || value.by === 'cancelled')
+            return { by: value.by, at };
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readSettlement(terminalId, approvalId, env = process.env) {
+    try {
+        return parseSettlement(readFileSync(settlementPath(terminalId, approvalId, env), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Settle the prompt with `settlement` unless it is settled already. Created
+ * whole and never overwritten: its contents go to a unique temp file, linked
+ * into place (EEXIST: someone settled it first). Returns the settlement that
+ * stands afterwards, ours or theirs; `undefined` only when the state can't be
+ * written or read, which every caller treats as "not by ProhostAI".
+ */
+export function settle(terminalId, approvalId, settlement, env = process.env) {
+    const file = settlementPath(terminalId, approvalId, env);
+    try {
+        ensurePrivateDir(path.dirname(file));
+        const temp = `${file}.new-${randomBytes(8).toString('hex')}`;
+        writeFileSync(temp, JSON.stringify(settlement), { mode: 0o600, flag: 'wx' });
+        try {
+            linkSync(temp, file);
+            return { settlement, ours: true };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    }
+    catch {
+        return { settlement: readSettlement(terminalId, approvalId, env), ours: false };
+    }
+    return { settlement: readSettlement(terminalId, approvalId, env), ours: false };
+}
+export function readWaiter(terminalId, approvalId, env = process.env) {
+    try {
+        const value = JSON.parse(readFileSync(waiterPath(terminalId, approvalId, env), 'utf8'));
+        if (value.approvalId !== approvalId)
+            return undefined;
+        if (typeof value.pid !== 'number' || typeof value.deadline !== 'number' || typeof value.fingerprint !== 'string') {
+            return undefined;
+        }
+        const saved = value.permissionRequest;
+        const data = saved?.data;
+        const permissionRequest = saved?.type === 'permission_request' && typeof saved.at === 'string' &&
+            Number.isFinite(Date.parse(saved.at)) && data && typeof data === 'object' && !Array.isArray(data) && data.approvalId === approvalId
+            ? { type: 'permission_request', at: saved.at, data } : undefined;
+        return {
+            approvalId, pid: value.pid, deadline: value.deadline, fingerprint: value.fingerprint,
+            ...(permissionRequest ? { permissionRequest } : {}),
+            ...(typeof value.transcript === 'string' ? { transcript: value.transcript } : {}),
+            ...(Array.isArray(value.toolUseIds) && value.toolUseIds.length > 0 && value.toolUseIds.every((id) => typeof id === 'string' && id.length > 0 && id.length <= 512) ? { toolUseIds: value.toolUseIds } : {}),
+            ...(value.overrideReported === true ? { overrideReported: true } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The approval ids with a `kind` file for `terminalId`. */
+function idsWith(kind, terminalId, env) {
+    if (!isValidId(terminalId))
+        return [];
+    const prefix = `${terminalId}.${kind}-`;
+    try {
+        return readdirSync(stateDir(env))
+            .filter((name) => name.startsWith(prefix) && name.endsWith('.json'))
+            .map((name) => name.slice(prefix.length, -'.json'.length))
+            .filter((id) => APPROVAL_ID.test(id));
+    }
+    catch {
+        return [];
+    }
+}
+const waiterIds = (terminalId, env) => idsWith('waiter', terminalId, env);
+/** A settlement no hook waits on any more is kept this long (a redelivery of its decision still reads it). */
+const SETTLEMENT_KEEP_MS = 30 * 60_000;
+/** Remove one prompt's files. */
+function forget(terminalId, approvalId, env) {
+    rmSync(waiterPath(terminalId, approvalId, env), { force: true });
+    rmSync(settlementPath(terminalId, approvalId, env), { force: true });
+}
+/**
+ * The hook registers itself as waiting for `waiter.approvalId`, before the
+ * server can hear of the prompt (so a decision that comes back at once finds
+ * it). Prior prompts, including completed ones, retain their fingerprints until
+ * turn progress: a delayed completion must never be mistaken for a new identical call.
+ */
+export function registerWaiter(terminalId, waiter, env = process.env, now = Date.now) {
+    for (const id of idsWith('decision', terminalId, env)) {
+        if (id === waiter.approvalId || readWaiter(terminalId, id, env))
+            continue;
+        const at = readSettlement(terminalId, id, env)?.at ?? 0;
+        if (now() - at > SETTLEMENT_KEEP_MS)
+            forget(terminalId, id, env);
+    }
+    writePrivateJson(waiterPath(terminalId, waiter.approvalId, env), waiter);
+}
+/**
+ * Whether a `PermissionRequest` hook in this terminal reported a prompt within `withinMs`: one
+ * waits now, or one was settled that recently. A `permission_prompt` notification then is the
+ * same prompt, already reported.
+ */
+export function recentPrompt(terminalId, env, now, withinMs, alive = processAlive) {
+    const waiting = waiterIds(terminalId, env).some((id) => {
+        const waiter = readWaiter(terminalId, id, env);
+        return waiter !== undefined && now < waiter.deadline && alive(waiter.pid);
+    });
+    if (waiting)
+        return true;
+    return idsWith('decision', terminalId, env).some((id) => now - (readSettlement(terminalId, id, env)?.at ?? 0) < withinMs);
+}
+export function menuState(terminalId, env = process.env, now = Date.now(), alive = processAlive) {
+    let state = 'clear';
+    const records = new Map();
+    for (const id of waiterIds(terminalId, env)) {
+        const waiter = readWaiter(terminalId, id, env);
+        if (!waiter)
+            continue;
+        const settlement = readSettlement(terminalId, id, env);
+        const running = alive(waiter.pid);
+        let held;
+        if (settlement === undefined) {
+            held = !running || now >= waiter.deadline ? 'open' : 'deciding';
+            // Answered in the terminal while its hook still waits (a "Yes" leaves the hook running): once
+            // Claude Code records the call over, the prompt is settled `local`, so its hook stops without
+            // printing and a decision arriving now is refused (`decide`).
+            if (held === 'deciding' && settleIfOver(terminalId, waiter, records, now, env))
+                held = undefined;
+        }
+        else if (settlement.by !== 'host') {
+            held = 'open';
+        }
+        else {
+            held = running ? 'deciding' : 'unconfirmed';
+        }
+        // A hook that no longer runs can't say its menu went: Escape or Ctrl+C after its wait ran out
+        // fires no hook. Claude Code's transcript does, once the call's permission flow is over.
+        if ((held === 'open' || held === 'unconfirmed') && resolvedInTranscript(waiter, records))
+            held = undefined;
+        if (held === 'open')
+            return 'open';
+        if (held === 'unconfirmed')
+            state = 'unconfirmed';
+        else if (held === 'deciding' && state === 'clear')
+            state = 'deciding';
+    }
+    return state;
+}
+/** Completed IDs are reported only once every local permission barrier has cleared. */
+export function completedApprovals(terminalId, env = process.env) {
+    if (menuState(terminalId, env) !== 'clear')
+        return [];
+    const records = new Map();
+    return waiterIds(terminalId, env).filter((id) => {
+        const waiter = readWaiter(terminalId, id, env);
+        return waiter?.permissionRequest !== undefined && resolvedInTranscript(waiter, records);
+    });
+}
+/** Retain the waiter until the server acknowledges the approval-scoped recovery event. */
+export function acknowledgeCompletedApproval(terminalId, approvalId, env) {
+    checked(terminalId, approvalId);
+    settle(terminalId, approvalId, { by: 'local', at: Date.now() }, env);
+    rmSync(waiterPath(terminalId, approvalId, env), { force: true });
+}
+/**
+ * Settle an unsettled prompt `local` if Claude Code's transcript shows its call over (`callIsOver`).
+ * Returns whether it is settled other than by ProhostAI afterwards (a decision may have won the race).
+ */
+function settleIfOver(terminalId, waiter, records, now, env) {
+    if (!resolvedInTranscript(waiter, records))
+        return false;
+    return settle(terminalId, waiter.approvalId, { by: 'local', at: now }, env).settlement?.by !== 'host';
+}
+/** `transcriptReleases` for a held prompt; each transcript is read once per `menuState`. */
+function resolvedInTranscript(waiter, records) {
+    const { transcript, toolUseIds } = waiter;
+    if (transcript === undefined || toolUseIds === undefined)
+        return false;
+    if (!records.has(transcript))
+        records.set(transcript, readTranscriptRecord(transcript));
+    const record = records.get(transcript);
+    return record !== undefined && callIsOver(record, toolUseIds);
+}
+/** Whether `approvalId` is a prompt a hook waits on (or waited on) here, so the hook answers it. */
+export function hookDecides(terminalId, approvalId, env = process.env) {
+    if (!isValidId(terminalId) || !APPROVAL_ID.test(approvalId))
+        return false;
+    return readWaiter(terminalId, approvalId, env) !== undefined || readSettlement(terminalId, approvalId, env) !== undefined;
+}
+/**
+ * The host, for a decision from ProhostAI: settle the prompt with it, only
+ * while its hook still waits (alive, before its deadline, unsettled). Writes
+ * nothing otherwise, and presses no key on any path.
+ */
+export function decide(terminalId, approvalId, decision, env = process.env, now = Date.now, alive = processAlive) {
+    if (!isValidId(terminalId) || !APPROVAL_ID.test(approvalId))
+        return 'local';
+    const standing = readSettlement(terminalId, approvalId, env);
+    if (standing)
+        return standing.by === 'host' ? 'already' : 'local';
+    const waiter = readWaiter(terminalId, approvalId, env);
+    if (!waiter || !alive(waiter.pid) || now() >= waiter.deadline)
+        return 'local';
+    // Its hook still waits after a "Yes" in the terminal: Claude Code's record of the call being over
+    // settles it there, so this decision, which would be ignored, is refused instead of acknowledged.
+    if (settleIfOver(terminalId, waiter, new Map(), now(), env))
+        return 'local';
+    const result = settle(terminalId, approvalId, { by: 'host', decision, at: now() }, env);
+    if (result.ours)
+        return 'delivered';
+    return result.settlement?.by === 'host' ? 'already' : 'local';
+}
+/**
+ * The hook, after registering: wait until its prompt is settled or `deadline`
+ * passes, then settle it `timeout` itself (unless a decision beat it to it).
+ * Returns ProhostAI's decision, or how it was otherwise settled.
+ */
+export async function awaitSettlement(terminalId, approvalId, deadline, env = process.env, now = Date.now, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), pollMs = 100) {
+    let checkedAt = Number.NEGATIVE_INFINITY;
+    for (;;) {
+        const standing = readSettlement(terminalId, approvalId, env);
+        if (standing)
+            return standing;
+        if (now() >= deadline)
+            return settle(terminalId, approvalId, { by: 'timeout', at: now() }, env).settlement;
+        // Answered "Yes" in the terminal, the hook still runs: once Claude Code records the call over, it
+        // is settled here, and the hook stops quietly instead of waiting out its deadline to post a stale
+        // "answer it in the terminal". About once a second: the transcript is parsed only as it grows.
+        if (now() - checkedAt >= TRANSCRIPT_RECHECK_MS) {
+            checkedAt = now();
+            const waiter = readWaiter(terminalId, approvalId, env);
+            if (waiter && resolvedInTranscript(waiter, new Map())) {
+                return settle(terminalId, approvalId, { by: 'local', at: now() }, env).settlement;
+            }
+        }
+        await sleep(Math.min(pollMs, Math.max(0, deadline - now())));
+    }
+}
+/** How often a waiting hook looks in the transcript for its call's end. */
+export const TRANSCRIPT_RECHECK_MS = 1_000;
+/**
+ * A `PostToolUse` for invocation `toolUseId`: that tool ran. If ProhostAI had settled its prompt with a
+ * deny, the terminal's "Yes" came first (Claude Code ignores a decision once the prompt is answered),
+ * and the record must not say "denied" for a command that ran.
+ *
+ * Exact IDs only, as for releases: exactly one held prompt names `toolUseId` among the invocations
+ * that could own it, and it names no other, so no other call (an identical one, or a subagent's) could
+ * be the prompt's own; the call that ran is the prompt's own call (its tool and input, `fingerprint`):
+ * a lone candidate may be a `Task`/`Agent` whose subagent prompted, and that Task finishing says
+ * nothing about the denied command; it was settled with a deny from ProhostAI, not reported yet.
+ * Anything less returns `undefined`: no correction, never a false one. Marks the prompt reported and
+ * returns its approval id. Retires nothing: only turn progress does (`markTurnAnswered`).
+ */
+export function beatenDeny(terminalId, toolUseId, toolName, toolInput, env = process.env) {
+    if (typeof toolUseId !== 'string' || !toolUseId)
+        return undefined;
+    const naming = waiterIds(terminalId, env)
+        .map((id) => readWaiter(terminalId, id, env))
+        .filter((waiter) => waiter?.toolUseIds?.includes(toolUseId) === true);
+    if (naming.length !== 1)
+        return undefined;
+    const [waiter] = naming;
+    if (waiter.overrideReported || waiter.toolUseIds.length !== 1)
+        return undefined;
+    if (toolFingerprint(toolName, toolInput) !== waiter.fingerprint)
+        return undefined;
+    const settlement = readSettlement(terminalId, waiter.approvalId, env);
+    if (settlement?.by !== 'host' || settlement.decision !== 'deny')
+        return undefined;
+    writePrivateJson(waiterPath(terminalId, waiter.approvalId, env), { ...waiter, overrideReported: true });
+    return waiter.approvalId;
+}
+/** A new user prompt or completed turn retires its permission waiters. */
+export function markTurnAnswered(terminalId, env = process.env, now = Date.now) {
+    for (const id of waiterIds(terminalId, env)) {
+        if (!readWaiter(terminalId, id, env))
+            continue;
+        settle(terminalId, id, { by: 'local', at: now() }, env);
+        rmSync(waiterPath(terminalId, id, env), { force: true });
+    }
+    forgetInvocations(terminalId, env);
+}

package/dist/codehost/events.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Code-thread events: what a Mac-hosted terminal tells ProhostAI about its
+ * thread — a prompt, a finished turn, a permission prompt, an interrupt.
+ *
+ * Both the daemon and the hook commands Claude Code / Codex run post here. The
+ * credential is not the paired API key: it is a narrow, expiring `host_events`
+ * token the relay mints for this machine over its control socket, kept in
+ * `$PROHOST_HOME/code-host/hook.json` (0600) and re-read on every post. So a
+ * hook in a shell that has been open for days uses whatever token the current
+ * daemon last wrote, and a machine whose daemon has been off for a day posts
+ * nothing rather than holding a long-lived secret in a file.
+ *
+ * Posting never costs the agent anything: every failure — no token yet, an
+ * expired one, a server without the endpoint (404), a closed thread — is
+ * swallowed. Never throws.
+ */
+export type CodeThreadEventType = 'start' | 'prompt' | 'permission_request' | 'prompt_local' | 'permission_resolved' | 'approval_overridden_locally' | 'stop' | 'failed' | 'interrupted' | 'stats';
+export interface CodeThreadEvent {
+    type: CodeThreadEventType;
+    /** ISO-8601. */
+    at: string;
+    data: Record<string, unknown>;
+}
+export interface HookConfig {
+    version: 1;
+    /** API base, e.g. `https://connect.prohost.ai`. */
+    endpoint: string;
+    token: string;
+    /** Epoch seconds. */
+    expires_at: number;
+}
+export declare const EVENT_POST_TIMEOUT_MS = 5000;
+export declare function hookConfigPath(env?: NodeJS.ProcessEnv): string;
+export declare function writeHookConfig(config: HookConfig, env?: NodeJS.ProcessEnv): void;
+/** The current config, or `undefined` when there is none, it is malformed, or it has expired. */
+export declare function readHookConfig(env?: NodeJS.ProcessEnv, nowMs?: number): HookConfig | undefined;
+export declare function codeThreadEventsPath(codeThreadId: string): string;
+export declare function event(type: CodeThreadEventType, data: Record<string, unknown>, nowMs?: number): CodeThreadEvent;
+/**
+ * POST one event. Returns the HTTP status, or 0 when nothing was sent or no
+ * answer came back. Never throws.
+ */
+export declare function postCodeThreadEvent(config: HookConfig | undefined, codeThreadId: string, body: CodeThreadEvent, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<number>;
+/** Something that takes a thread's events and posts them, fail-soft. */
+export interface CodeThreadEventSink {
+    post(codeThreadId: string, body: CodeThreadEvent): Promise<number>;
+}
+/** The daemon's sink: re-reads `hook.json` for every post, like the hooks do. */
+export declare function fileEventSink(env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): CodeThreadEventSink;