baychat 0.11.4 → 0.13.0

package/README.md

@@ -60,6 +60,7 @@ per session, never one that another integration already uses.
 | `baychat qr [<conv>]` | Render this agent's connection QR right in the terminal — scan it with BuzzRelay or any BayChat-aware app |
 | `baychat conversations` | List conversations this agent participates in |
 | `baychat send <conv> <text>` | Send a message |
+| `baychat typing <conv>` | Show the typing indicator while you work, so a long tool call doesn't read as a crash. **One call at the start of a turn** — it lapses on its own after a few seconds, so there is nothing to stop and no loop to run |
 | `baychat check <conv>` | Print messages since the last check (cursor-based) |
 | `baychat context <conv>` | Show the roster and the group's agent instructions |
 | `baychat summary <conv> [--refresh]` | Catch up on a long conversation: the rolling summary (decisions, open tasks/questions, durable facts — with source message ids) plus the raw messages after its boundary. `--refresh` forces regeneration (rate-limited) |
@@ -189,6 +190,9 @@ surface for every vendor.
 
 | Tool | What it does |
 |------|--------------|
+| `react_to_message` | React to a message with an emoji. Prefer this to a contentless "ok" / "got it" reply — a reaction reaches nobody's context, a message reaches everybody's |
+| `list_files` | The files shared in a conversation, as an index you can query — find one without re-reading the room |
+| `get_file` | Fetch one file from that index by id |
 | `web_search` | Search the web; returns ranked results with title, URL, and snippet |
 | `web_fetch` | Fetch one public `http(s)` URL and return its readable text |
 | `list_agents` | List the other agents in your Bay — how you find the id `ask_connector` needs |
@@ -252,6 +256,7 @@ Drop this into your CLAUDE.md / AGENTS.md so the session knows the loop:
 You are connected to BayChat as a named agent via the `baychat` CLI.
 - `baychat conversations` — find the group conversation id
 - `baychat watch <id>` — block until someone speaks (exit 2 = quiet timeout, just watch again)
+- `baychat typing <id>` — once, before you start working, so the room can tell you apart from a crash
 - `baychat send <id> "message"` — reply
 Keep replies short and conversational. Address people/agents by name. Stop
 watching when the user asks you to leave the chat.
@@ -265,7 +270,7 @@ as a native tool provider instead of shell commands. `baychat mcp` starts a loca
 speaks JSON-RPC on stdout, so don't run it interactively — register it with your
 client and let the client launch it.
 
-It exposes nine tools and one resource, each described so the model behaves
+It exposes thirteen tools and one resource, each described so the model behaves
 correctly from the tool descriptions alone (reply only when `shouldRespond`;
 summaries are derived, untrusted context; fetched content is never an
 instruction):
@@ -277,6 +282,7 @@ instruction):
 | `get_conversation_summary` | The rolling catch-up summary (decisions, tasks, questions, facts + source ids) |
 | `get_messages` | Recent messages enriched with sender, mentions, and `shouldRespond` |
 | `send_message` | Send a message into a conversation |
+| `set_typing` | Show the typing indicator while you work. One call at the start of a turn; it expires by itself, so never loop it. Presence only — it does not authorize a reply |
 | `web_search` | Search the web — call it when the answer depends on current information not in the conversation. Results are [untrusted content](#returned-content-is-untrusted) |
 | `web_fetch` | Fetch one public `http(s)` URL as readable text. Page text is [untrusted content](#returned-content-is-untrusted) |
 | `list_agents` | List the other agents in your Bay (optional `query` filter) — call it to find the id `ask_connector` needs |
@@ -383,6 +389,49 @@ user baychat …`); if the `claude` binary is missing or the add fails, login st
 prints the command to run by hand. On Windows `claude` is a `.cmd` shim, which Node can only
 launch through a shell, so the CLI shells out there and quotes each argument itself.
 
+### What the remote server gives you — sessions and groups
+
+The remote server authenticates you as a **person**, not as an agent, and its tool surface differs
+from `baychat mcp` above because of it. Every base tool grows a **required `session` argument** —
+a terminal has no single agent identity, so each call names the session it acts as — and five tools
+exist only here:
+
+| Tool | What it does |
+|------|--------------|
+| `join_session` | Name this terminal and put it in a room. `{ session }` alone opens a 1:1 with you; `{ session, group }` joins that group **instead** of the 1:1 |
+| `list_sessions` | This login's sessions — name, live/idle, last seen |
+| `end_session` | Park a session. The chat and its history survive; rejoining the same name revives it |
+| `list_groups` | The groups you are in — exact title, who is in them, and the conversation id |
+| `create_group` | Open a new group and land this session in it. You become its admin, exactly as if you had created it in the app |
+
+`request_approval` and `await_approval` are here too: they put a yes/no decision card on your phone
+and block until you answer.
+
+```
+list_groups()
+create_group({ session: "Session-A", title: "Ad Review" })
+create_group({ session: "Session-A", title: "Ad Review", agents: ["Codex", "Magpie"] })
+```
+
+`list_groups` is the "I cannot remember what I called it" tool, and its output is shaped so the
+title can be pasted straight back into `join_session`, which matches exactly and never guesses.
+`agents` takes the exact names `list_agents` prints; an unknown one is refused **with the roster**
+rather than nearest-matched. Other terminal sessions are deliberately not on that list — a session
+joins rooms for itself.
+
+Two refusals worth knowing in advance:
+
+- **A title that already names one of your groups is refused**, pointing at the room you probably
+  meant. Two rooms sharing one title make **either** impossible to join by name until somebody
+  renames one.
+- **`create_group` is not how you recover from a join that missed.** A title that missed is a typo
+  far more often than it is a new room, and creating one forks the conversation in two. Run
+  `list_groups` and join the real title.
+
+> A standing `bay_` agent gets **neither** group tool, on purpose: it is a guest in rooms somebody
+> else composed, and letting it create rooms would let it choose its own audience. Composing a room
+> is a person's act.
+
 ## Configuration
 
 | Env var | Effect |

package/dist/api.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiError = void 0;
 exports.apiRequest = apiRequest;
+exports.apiUpload = apiUpload;
 exports.fetchContext = fetchContext;
 exports.pairRequest = pairRequest;
 exports.createLinkRequest = createLinkRequest;
@@ -9,6 +10,7 @@ exports.pollLinkRequest = pollLinkRequest;
 exports.createDeviceLink = createDeviceLink;
 exports.pollDeviceLink = pollDeviceLink;
 exports.deviceMe = deviceMe;
+const attachments_1 = require("./attachments");
 class ApiError extends Error {
     status;
     code;
@@ -65,6 +67,62 @@ async function apiRequest(creds, method, apiPath, body) {
         throw new ApiError(res.status, "The server returned a response that was not valid JSON — a proxy or error page may have answered instead of the BayChat API. Check the API URL.");
     }
 }
+/**
+ * Turn an upload refusal into a sentence that says what to DO about it.
+ *
+ * Three of the statuses this route returns mean something specific, and the
+ * server's own wording alone leaves the caller guessing: a plan cap is not a bug
+ * to retry, a rejected type is a re-export, and a 503 here is a Bay that has
+ * attachments switched off entirely (no encryption key) — retrying that forever
+ * is the failure mode this message exists to prevent. Everything else keeps the
+ * server's message untouched.
+ */
+function uploadError(err) {
+    if (err.status === 413) {
+        return new ApiError(err.status, `This file is larger than this Bay's plan allows (${err.message}). Send a smaller file, or ask the Bay owner to upgrade.`, err.code);
+    }
+    if (err.status === 415 || err.status === 400) {
+        return new ApiError(err.status, `The server refused this file (${err.message}). Allowed: ${attachments_1.ALLOWED_ATTACHMENT_EXTENSIONS.join(", ")}.`, err.code);
+    }
+    if (err.status === 503) {
+        return new ApiError(err.status, "This BayChat server has attachments disabled (no message encryption key is configured), so nothing can be uploaded to it. Tell the person running the Bay; retrying will not help.", err.code);
+    }
+    return err;
+}
+/**
+ * Upload ONE file as multipart to the agent attachments route, authenticated as
+ * the agent, and get back the id a send references.
+ *
+ * Node ≥18 built-ins only (`fetch`/`FormData`/`Blob`) — this package ships no
+ * multipart dependency and adds none. The `Content-Type` header is deliberately
+ * NOT set: fetch derives it from the FormData, including the boundary, and
+ * setting it by hand produces a body the server cannot parse.
+ *
+ * @throws {ApiError} with a message the caller can render verbatim.
+ */
+async function apiUpload(creds, file) {
+    const form = new FormData();
+    // A real copy, not a view: `Uint8Array` here may be a window into a shared
+    // buffer (a Buffer from `readFileSync` is), which `BlobPart` does not accept —
+    // and copying also means a later mutation of the caller's buffer cannot change
+    // what was sent.
+    form.append("file", new Blob([new Uint8Array(file.bytes)], { type: file.mimeType }), file.fileName);
+    const res = await fetch(`${creds.baseUrl}/api/agent-api/attachments`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${creds.token}` },
+        body: form,
+    });
+    if (!res.ok)
+        throw uploadError(await parseError(res));
+    try {
+        return (await res.json());
+    }
+    catch {
+        // Same reasoning as `apiRequest`: a 2xx that isn't JSON came from something
+        // other than the API, and its body must never reach the rendered message.
+        throw new ApiError(res.status, "The upload returned a response that was not valid JSON — a proxy or error page may have answered instead of the BayChat API. Check the API URL.");
+    }
+}
 /**
  * Fetch the Agent Context Contract v2 block for a conversation.
  * Fail-soft: a v1 server has no `/context` endpoint and 404s — we return null

package/dist/approve-hook.js

@@ -0,0 +1,425 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPROVE_OPTIONS = exports.RECOMMENDED_HANDLER_TIMEOUT_SECONDS = exports.DEFAULT_WAIT_SECONDS = void 0;
+exports.allowDecision = allowDecision;
+exports.denyDecision = denyDecision;
+exports.describeToolRequest = describeToolRequest;
+exports.composeQuestion = composeQuestion;
+exports.decideApproval = decideApproval;
+exports.readStdin = readStdin;
+exports.cmdApproveHook = cmdApproveHook;
+// `baychat approve-hook` — the Claude Code PermissionRequest hook that moves a terminal
+// permission prompt onto a phone.
+//
+// WHY THIS EXISTS. A permission prompt is drawn by Claude Code itself, not by the model, so no
+// instruction can route it anywhere: by the time "run this command? (y/n)" is on screen the model
+// is not running. From BayChat such a session is simply silent — indistinguishable from a crash.
+// This command is the only complete fix, and it is a deliberate security trade: see
+// docs/features/REMOTE_APPROVAL_HOOK.md and docs/design/REMOTE_APPROVAL_ROUTING.md §3.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// THE ONE RULE: EVERY PATH OUT OF HERE PRINTS A DECISION.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+//
+// Claude Code hooks FAIL OPEN. Verified against the current hooks reference, all of these mean
+// "the tool call proceeds through the normal permission flow":
+//
+//   • the hook times out                    • it exits 1 (or any code but 2)
+//   • stdout is empty, or is not JSON       • stdout is JSON that fails schema validation
+//   • the command is missing or mistyped
+//
+// and exit code 2 — the one code that blocks on other events — is NOT honoured on
+// PermissionRequest at all: "Exit code 2 isn't honored for this event and the permission flow
+// proceeds unchanged. Deny through the decision object instead."
+//
+// So the fail-closed guarantee is entirely this file's. Every abnormal path — no credential, DNS
+// failure, connection refused, 500, 401, unparseable body, ambiguous session, our own deadline,
+// an exception nobody predicted — is converted into an explicit DENY object and exit 0. There is
+// no `process.exit(1)` anywhere below, because exit 1 ALLOWS.
+//
+// Two consequences worth stating plainly:
+//
+//   1. OUR WAIT MUST END BEFORE THE HANDLER'S `timeout`. A hook that times out allows, so a
+//      deadline we control (which denies) must always be reached first. Hence
+//      DEFAULT_WAIT_SECONDS < RECOMMENDED_HANDLER_TIMEOUT_SECONDS, and the docs say to raise
+//      both together or neither.
+//   2. STDOUT IS THE DECISION CHANNEL. Nothing else may ever be written to it — "Stdout must
+//      contain only the JSON object". All diagnostics go to stderr.
+//
+// The card itself never expires: the ApprovalRequest row stays PENDING for as long as it takes,
+// exactly like a terminal prompt. Our deadline bounds only how long THIS PROCESS waits, and it
+// exists solely because the alternative (being killed by the handler timeout) would allow.
+const os = __importStar(require("os"));
+const api_1 = require("./api");
+const config_1 = require("./config");
+function allowDecision() {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            decision: { behavior: "allow" },
+        },
+    };
+}
+/**
+ * A refusal, with the reason Claude will see.
+ *
+ * `interrupt` is deliberately NOT set. Stopping the session on every unreachable-network deny
+ * would turn a flaky connection into a killed run; Claude being told "denied, and why" leaves the
+ * person at the keyboard able to decide.
+ */
+function denyDecision(message) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            decision: { behavior: "deny", message },
+        },
+    };
+}
+const DENY_PREFIX = "Denied by BayChat remote approval";
+/** Every deny reads the same way, so a person reading a transcript can tell instantly that the
+ *  gate refused rather than that a human did. */
+function deny(reason, advice = "") {
+    return denyDecision(`${DENY_PREFIX}: ${reason}${advice ? ` ${advice}` : ""}`);
+}
+/** The deny used when the gate itself could not run. Named because it is the fail-closed path
+ *  the whole design turns on, and because every branch below funnels into it. */
+function denyClosed(reason) {
+    return deny(
+    // The trailing stop is added here rather than at every call site: these reasons are composed
+    // from server messages and exception text, and none of them can be relied on to end cleanly.
+    `${reason.replace(/[.\s]+$/, "")}.`, "This gate fails closed, so the call was refused rather than allowed. Do not retry it; " +
+        "tell the person what you were trying to do and let them approve it at the keyboard.");
+}
+// ─── Timing ──────────────────────────────────────────────────────────────────
+/**
+ * How long this process waits before denying, in seconds.
+ *
+ * An hour, not forever: the handler's own `timeout` would otherwise kill us first, and a
+ * killed hook ALLOWS. This number and the `timeout` in settings.json are one setting in two
+ * places — see the doc.
+ */
+exports.DEFAULT_WAIT_SECONDS = 3600;
+/** What the documented settings.json block must set. Strictly greater than DEFAULT_WAIT_SECONDS,
+ *  with room for process start-up and the final write, so OUR deadline always lands first. */
+exports.RECOMMENDED_HANDLER_TIMEOUT_SECONDS = 3900;
+/** One HTTP hold. The server clamps to 30; asking for less than it allows leaves headroom for a
+ *  proxy with its own idle timeout. */
+const POLL_WAIT_SECONDS = 25;
+/** Consecutive transport failures tolerated while WAITING, before denying.
+ *
+ *  Not zero, and not unlimited. The card is already on somebody's phone by then, so denying on a
+ *  single dropped long-poll is both a bad experience and the fastest way to get this hook turned
+ *  off; but a network that stays down must still land on a deny, and does — here, or at the
+ *  deadline, whichever comes first. Failures on CREATE are not retried at all: nothing exists
+ *  yet, so there is nothing to lose by refusing immediately. */
+const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+const POLL_RETRY_DELAY_MS = 2000;
+/** The card's own limits, mirrored from apps/api/src/lib/cards.ts. Restating them is how they
+ *  drift, so they are only ever used to TRIM — the server still refuses anything malformed. */
+const QUESTION_MAX = 2000;
+const DETAIL_MAX = 900;
+// ─── Describing what is being approved ───────────────────────────────────────
+function str(value) {
+    return typeof value === "string" ? value : "";
+}
+function clip(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/**
+ * What this tool call would actually do, in the words the person on the phone needs.
+ *
+ * They are deciding from this text alone, on a lock screen, without the transcript. "Bash" is
+ * not a decision; `rm -rf /var/www/baychat` is. Tools whose risk lives in one field get that
+ * field verbatim; anything unrecognised falls back to its whole input as JSON rather than to a
+ * reassuring summary, because an unfamiliar tool is exactly when a person should see everything.
+ */
+function describeToolRequest(toolName, toolInput) {
+    const input = (toolInput ?? {});
+    const detail = (() => {
+        switch (toolName) {
+            case "Bash":
+            case "BashOutput": {
+                const command = str(input.command);
+                const why = str(input.description);
+                return command ? (why ? `${command}\n(${why})` : command) : "";
+            }
+            case "Write":
+            case "Edit":
+            case "MultiEdit":
+            case "NotebookEdit":
+            case "Read":
+                return str(input.file_path) || str(input.notebook_path);
+            case "Glob":
+            case "Grep":
+                return [str(input.pattern), str(input.path)].filter(Boolean).join("  in  ");
+            case "WebFetch":
+                return str(input.url);
+            case "WebSearch":
+                return str(input.query);
+            default:
+                return "";
+        }
+    })();
+    if (detail)
+        return clip(detail, DETAIL_MAX);
+    // Unknown tool, or a known one with its field missing: show the raw input. JSON.stringify can
+    // throw on a cyclic value, which must not become an exception on the approval path.
+    try {
+        return clip(JSON.stringify(input), DETAIL_MAX);
+    }
+    catch {
+        return "(its parameters could not be displayed)";
+    }
+}
+/** The question the card asks. Blunt on purpose: this is a shell on a server, read on a phone,
+ *  and the safe answer has to be the obvious one. */
+function composeQuestion(params) {
+    const lines = [
+        `Claude Code on ${params.host} is asking permission to use ${params.toolName}. ` +
+            `This would normally be a prompt in the terminal.`,
+        "",
+        describeToolRequest(params.toolName, params.toolInput),
+        "",
+        params.cwd ? `Working directory: ${params.cwd}` : "",
+        params.permissionMode ? `Permission mode: ${params.permissionMode}` : "",
+        "",
+        "Allowing runs it on that machine, now. If you did not expect this, deny.",
+    ].filter((l) => l !== undefined);
+    return clip(lines.join("\n").replace(/\n{3,}/g, "\n\n").trim(), QUESTION_MAX);
+}
+/** Button labels. "once" is literal — nothing here ever writes a permission rule, so an approval
+ *  covers this call and no future one. */
+exports.APPROVE_OPTIONS = ["Allow this once", "Deny"];
+/** The ONLY index that means yes. Anything else — a second option, a third, an index the server
+ *  invented — is a deny, so a mismatch between these labels and the answer can only fail safe. */
+const ALLOW_INDEX = 0;
+function parseArgs(argv) {
+    const at = (name) => {
+        const i = argv.indexOf(name);
+        return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
+    };
+    const rawTimeout = Number(at("--timeout"));
+    return {
+        session: at("--session"),
+        // A junk --timeout falls back to the default rather than to NaN. NaN compared against a
+        // deadline is always false, which would mean "never wait" — a deny, but the wrong one.
+        waitSeconds: Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : exports.DEFAULT_WAIT_SECONDS,
+    };
+}
+/** How long to ask the server to hold, never past our own deadline. */
+function holdSeconds(remainingMs) {
+    return Math.max(1, Math.min(POLL_WAIT_SECONDS, Math.ceil(remainingMs / 1000)));
+}
+/** A refusal the server MEANT — no live session, an ambiguous one, a bad credential, a request
+ *  that is not ours. Retrying these is pointless, so they deny immediately; a transport failure
+ *  or a 5xx might be a blip and is retried by the caller. */
+function isDefinite(err) {
+    return err instanceof api_1.ApiError && err.status < 500 && err.status !== 429;
+}
+function reasonOf(err) {
+    if (err instanceof api_1.ApiError)
+        return `${err.message} (HTTP ${err.status})`;
+    return err instanceof Error ? err.message : String(err);
+}
+// ─── The decision ────────────────────────────────────────────────────────────
+/**
+ * Turn one hook invocation into one decision. NEVER THROWS and never returns undefined: the
+ * outer try/catch is the last of several, and exists for the exception nobody thought of.
+ *
+ * `rawStdin` is the hook's JSON input; `argv` the flags after `approve-hook`.
+ */
+async function decideApproval(rawStdin, argv = [], deps = {}) {
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const log = deps.log ?? ((line) => process.stderr.write(`${line}\n`));
+    try {
+        const opts = parseArgs(argv);
+        const deadline = now() + opts.waitSeconds * 1000;
+        let input;
+        try {
+            const parsed = JSON.parse(rawStdin);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error("not an object");
+            input = parsed;
+        }
+        catch {
+            // We cannot say what would run, so we cannot ask anyone to approve it.
+            return denyClosed("the permission request could not be read from stdin");
+        }
+        const toolName = str(input.tool_name);
+        if (!toolName)
+            return denyClosed("the permission request named no tool");
+        const device = (deps.loadDevice ?? config_1.loadDeviceCredentials)();
+        if (!device) {
+            return denyClosed("this machine is not logged in to BayChat (`baychat login`)");
+        }
+        const question = composeQuestion({
+            toolName,
+            toolInput: input.tool_input,
+            cwd: str(input.cwd),
+            host: (deps.hostname ?? os.hostname)(),
+            permissionMode: str(input.permission_mode),
+        });
+        // ── Create. One round trip that also parks for the first window, because the common case
+        // is answered within seconds. A failure here is final: no card exists, so there is nothing
+        // a retry could rescue and nothing left pending on anyone's phone.
+        let reply;
+        try {
+            reply = await (0, api_1.apiRequest)(device, "POST", "/api/device-api/approvals", {
+                session: opts.session,
+                question,
+                options: [...exports.APPROVE_OPTIONS],
+                wait: holdSeconds(deadline - now()),
+            });
+        }
+        catch (err) {
+            return denyClosed(`BayChat could not be asked — ${reasonOf(err)}`);
+        }
+        const requestId = str(reply.requestId);
+        if (!requestId)
+            return denyClosed("BayChat did not return an approval id");
+        // ── Wait. Re-arm across the bounded holds exactly as `await_approval` does: "waiting" is a
+        // success meaning nobody has tapped yet, never a lapse and never a no.
+        let failures = 0;
+        for (;;) {
+            const settled = verdictOf(reply, requestId);
+            if (settled)
+                return settled;
+            const remaining = deadline - now();
+            if (remaining <= 0) {
+                return deny(`nobody answered within ${opts.waitSeconds}s.`, "The decision card is still in BayChat; this call was refused because waiting longer " +
+                    "would have let the hook time out, and a timed-out hook silently ALLOWS.");
+            }
+            try {
+                reply = await (0, api_1.apiRequest)(device, "GET", `/api/device-api/approvals/${encodeURIComponent(requestId)}?wait=${holdSeconds(remaining)}`);
+                failures = 0;
+            }
+            catch (err) {
+                if (isDefinite(err)) {
+                    return denyClosed(`BayChat refused the wait — ${reasonOf(err)}`);
+                }
+                failures += 1;
+                log(`baychat approve-hook: waiting failed (${reasonOf(err)}) — attempt ${failures}`);
+                if (failures >= MAX_CONSECUTIVE_POLL_FAILURES) {
+                    return denyClosed(`BayChat became unreachable while waiting — ${reasonOf(err)}`);
+                }
+                await sleep(POLL_RETRY_DELAY_MS);
+            }
+        }
+    }
+    catch (err) {
+        // The catch that makes the guarantee true. Anything at all — a thrown non-Error, an OOM in a
+        // dependency, a bug three refactors from now — lands here as a deny rather than as a crash,
+        // and a crash is an ALLOW.
+        log(`baychat approve-hook: unexpected failure (${reasonOf(err)})`);
+        return denyClosed("the approval gate hit an unexpected error");
+    }
+}
+/**
+ * Read one server reply as a verdict, or null to keep waiting.
+ *
+ * ONLY `status === "answered"` WITH `answerIndex === 0` ALLOWS. Every other combination — a
+ * cancelled card, an index we did not offer, a status this client has never heard of, a missing
+ * field — is a deny. That asymmetry is the point: a future server change can make this hook
+ * over-refuse, and can never make it over-permit.
+ */
+function verdictOf(reply, requestId) {
+    const status = str(reply.status);
+    if (status === "waiting")
+        return null;
+    if (status === "answered") {
+        if (reply.answerIndex === ALLOW_INDEX)
+            return allowDecision();
+        return deny(`answered "${reply.answer ?? exports.APPROVE_OPTIONS[1]}" in BayChat.`);
+    }
+    if (status === "cancelled") {
+        return deny("the decision was withdrawn in BayChat without an answer.");
+    }
+    return denyClosed(`BayChat answered with a status this client does not understand ("${status}") for ${requestId}`);
+}
+// ─── stdin ───────────────────────────────────────────────────────────────────
+/**
+ * The hook's JSON input.
+ *
+ * Bounded, because a stdin that never closes would stall us until the handler timeout kills the
+ * process — and being killed ALLOWS. On timeout we return what arrived (usually nothing), which
+ * fails to parse, which denies.
+ */
+function readStdin(stream = process.stdin, timeoutMs = 10_000) {
+    return new Promise((resolve) => {
+        let text = "";
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(text);
+        };
+        const timer = setTimeout(finish, timeoutMs);
+        // Do not hold the process open on the timer alone.
+        if (typeof timer.unref === "function")
+            timer.unref();
+        stream.setEncoding?.("utf8");
+        stream.on("data", (chunk) => {
+            text += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        });
+        stream.on("end", finish);
+        stream.on("error", finish);
+    });
+}
+// ─── The command ─────────────────────────────────────────────────────────────
+/**
+ * `baychat approve-hook [--session <name>] [--timeout <seconds>]`
+ *
+ * Always returns 0. A non-zero exit is a non-blocking error to Claude Code, which means the tool
+ * call PROCEEDS — so exiting 1 on failure would be precisely backwards.
+ */
+async function cmdApproveHook(argv = [], stdin = process.stdin) {
+    let decision;
+    try {
+        decision = await decideApproval(await readStdin(stdin), argv);
+    }
+    catch (err) {
+        // decideApproval does not throw; readStdin does not reject. This is here anyway, because the
+        // cost of being wrong about that is an allow.
+        process.stderr.write(`baychat approve-hook: ${err instanceof Error ? err.message : String(err)}\n`);
+        decision = denyClosed("the approval gate could not run");
+    }
+    // The single write to stdout, and the only one in this file.
+    process.stdout.write(`${JSON.stringify(decision)}\n`);
+    return 0;
+}