approval-md 0.2.0 → 0.3.0

package/dist/src/cli/codex-bridge.d.ts

@@ -0,0 +1,819 @@
+/**
+ * `approval codex bridge`: approval.md as the client of Codex's app-server
+ * protocol (APRV-361, adopting APRV-349's recommendation).
+ *
+ * ## Why this exists
+ *
+ * The native Codex hook refuses every shell call. A `Bash` pre-event carries
+ * `tool_input` keys exactly `["command"]`, so the adapter cannot bind the
+ * directory the command will run in, and it answers
+ * `hook-unsupported-execution-context` rather than approve bytes whose meaning
+ * it does not know (APRV-310, APRV-311). The app-server protocol is a different
+ * shape: Codex stops before it acts, asks its client, and waits, and the
+ * question it asks carries `cwd` on the same frame as the command, minted by
+ * the harness runtime rather than reported by the model.
+ *
+ * `docs/codex-app-server-bridge.md` is the evidence and the recommendation.
+ * Read the recommendation before changing anything here: this is an ADVISORY
+ * checkpoint for everyday Codex sessions this runtime starts, and it is not a
+ * boundary. The auto-reviewer can resolve a question before this client sees
+ * it, and the approval policy and sandbox posture decide how many questions
+ * exist at all. Both are governed by the harness's own configuration, which
+ * this project does not attest. The claim this verb supports is "this client
+ * decided every question this app-server child asked in this session", and
+ * nothing wider. See the custody section below for which word in that sentence
+ * is load-bearing.
+ *
+ * ## Custody: the server is this process's own child (APRV-365)
+ *
+ * A pending approval request is replayed to whatever connects NEXT, so "who
+ * may connect" is a real question about any app-server, and it is the question
+ * the follow-up list filed. For this verb it is answered by construction: the
+ * server is started here, by {@link driveSession}, as a child process over
+ * stdio pipes. There is no socket, nothing binds a path, and no other process
+ * has a file descriptor to speak on. The custody rule is the operating
+ * system's rather than this runtime's, which is the strongest kind available
+ * and the only kind this project would not have to attest.
+ *
+ * Two consequences worth stating rather than leaving to be inferred. Within
+ * one run there is no replay hazard at all: a question this client is asked
+ * cannot reach another client, because there is no other client. And the claim
+ * is scoped to THIS CHILD and THIS SESSION: a Codex started outside this
+ * arrangement is a different process with a different connection, and nothing
+ * here observes it, exactly as `docs/codex-activation.md` says of a Codex
+ * started outside the confined session.
+ *
+ * What this verb deliberately does NOT do is inspect the server command for a
+ * shape that would attach to something already running instead of starting a
+ * child. That would be a guess at another program's command line, which this
+ * repository has no record of, and a check written against a guessed shape
+ * finds nothing while reporting that it looked (the trap APRV-379 names and
+ * APRV-364's item reader is careful about). The property is stated and true;
+ * an operator who passes `-- <something that attaches>` after the separator has
+ * left the arrangement this section describes, and the report's claim is then
+ * about a session this verb did not establish.
+ *
+ * ## It reuses the hook's flow; it does not fork it
+ *
+ * Every decision is `cli/hook.ts`'s {@link decideHarnessCall}: the same
+ * classifier over `{command, cwd}`, the same human-only refusal, the same
+ * unruled `harness.launch.*` refusal, the same sandbox requirement, the same
+ * loop floor and unattended guard, and the same register, request and wait
+ * against the verified view. What changes is only where the answer goes: a
+ * JSON-RPC reply on the connection instead of a decision object on stdout.
+ *
+ * The request is translated into the hook's own `HookInput` — tool `Bash`,
+ * `tool_input.command` the string the server sent, `cwd` the directory the
+ * server named — and nothing else is invented. Both fields come from the
+ * server, which is what makes them usable: a `cwd` the model reported would be
+ * a self-reported field reducing scrutiny (SPEC §11.1 invariant 4).
+ *
+ * ## The deadline is the policy's, not a harness ceiling
+ *
+ * Every hook adapter answers inside a ceiling its harness sets, and the retry
+ * grace and adopt-on-retry machinery exist so a denial-by-deadline is
+ * recoverable. This transport has no timeout at all (`docs/codex-app-server-bridge.md`,
+ * question 2), so the wait here defaults to the policy's `approval_ttl`: a
+ * human who answers in eleven minutes is answering rather than arriving too
+ * late. `--wait` overrides it; nothing shortens the request's own TTL.
+ *
+ * ## What it answers, and what it never answers
+ *
+ * `accept` and `decline` only, in the vocabulary the request advertised through
+ * `availableDecisions`, and never `acceptForSession`, `cancel` or `abort`.
+ * `acceptForSession` converts one decision into standing authority for a whole
+ * session, which is a grant shape this project does not have. `cancel` and
+ * `abort` mean "stop the turn", which is a different act from "no to this
+ * action", and sending one would record an interruption as a denial.
+ *
+ * That rule is carried by the TYPE since APRV-367, not by a reviewer's memory:
+ * every reply word is a {@link BridgeDecisionWord}, whose eight inhabitants are
+ * the four spellings of yes and the four of no, and {@link encodeDecision} is
+ * the one place a decision becomes bytes and re-asks the question at runtime. A
+ * word outside the vocabulary is unconstructible, and were one to arrive anyway
+ * the reply becomes a decline, since the only safe substitute for a word you
+ * cannot name is no.
+ *
+ * ## The two file-change APIs, and the correlation (APRV-363, APRV-379)
+ *
+ * The LEGACY `applyPatchApproval` carries its `fileChanges` map on the request
+ * itself, so there is nothing to correlate and nothing to re-render. Since
+ * APRV-363 it goes through the same `decideHarnessCall` the exec half uses,
+ * classified by the paths it names and bound with the change as it arrived plus
+ * its digest. A request carrying a map and no directory is refused exactly as
+ * an exec request with no `cwd` is: a relative path resolves somewhere, and a
+ * directory this client guessed would be a guess the grant is bound to.
+ *
+ * An `item/fileChange/requestApproval` on the ITEM-BASED API carries no
+ * content: `threadId`, `turnId`, `itemId`, `startedAtMs`, `reason` and
+ * `grantRoot`, and nothing else. The bytes arrived EARLIER, on the
+ * `item/started` notification for that item, whose `item.changes` is an array
+ * of `{path, kind, diff}` (observed on 0.155.0; the frame is in
+ * `docs/codex-app-server-bridge.md`, question 1). Since APRV-379 this verb
+ * keeps every item the thread announces, by item id, and answers the request
+ * against the frame that id names. What reaches the classifier is the change
+ * set the server sent, in the shape it sent it: the paths take their classes
+ * and the payload binds the changes verbatim with a digest over them as
+ * received. Nothing is re-rendered into an `apply_patch` envelope and nothing
+ * parses `diff`.
+ *
+ * The correlation is where an approval could authorize bytes nobody classified,
+ * so every way the two frames could fail to be about one change is a refusal:
+ * an id no `item/started` announced, an id naming an item that is not a
+ * `fileChange`, a frame with no readable change set, and a request naming a
+ * thread or a turn the frame does not, are all `bridge-file-change-unbound`.
+ * An item whose `item/completed` arrived BEFORE the question is
+ * `bridge-file-change-already-completed`: a change that finished before it was
+ * asked about is not a change this client is in a position to decide.
+ *
+ * A server request this verb does not recognise is declined too, on the same
+ * rule: a question nobody classified is not a question to answer yes to.
+ *
+ * ## The approval policy is pinned, and the pin is checked (APRV-366)
+ *
+ * The thread starts with `approvalPolicy: "untrusted"`, which is `UnlessTrusted`
+ * on the wire and the only variant under which every command and every patch
+ * asks. Under `on-request` or `never` an unknown fraction of the session never
+ * reaches this client, and "this client decided every question it was asked"
+ * would still be true while meaning nothing. There is no flag.
+ *
+ * What the verb can prove about it depends on the server. A `thread/start` the
+ * server refuses stops the run, carrying its error verbatim, which is where a
+ * refusal of the value itself lands. A server that reports an effective policy
+ * of its own, on `thread/start`'s result or on a thread notification, stops the
+ * run when that policy is not the pinned one. A server that reports nothing is
+ * run against, and the report then claims only what happened: the pin was
+ * requested and no frame confirmed it.
+ *
+ * ## A probe turn runs first, and it can stop the session (APRV-364)
+ *
+ * Codex carries a server-side auto-reviewer that can resolve an approval with a
+ * model call before this client is asked, and tells the client afterwards
+ * through `item/autoApprovalReview` notifications. Whether it runs is a setting
+ * in the harness's own configuration, which this project does not attest, and
+ * there is no frame in the observed vocabulary where the server reports it. So
+ * it cannot be READ, and the only way to establish anything is to watch what
+ * happens to one command.
+ *
+ * Every start therefore runs a PREFLIGHT turn asking for one harmless command
+ * ({@link PROBE_COMMAND}) before the operator's own turn, with no flag to skip
+ * it. Three outcomes, told apart by the command-item notifications:
+ *
+ * - an approval request for it reaches this client: the run continues, and the
+ *   report records the pin as confirmed by OBSERVATION;
+ * - a command ran and no request arrived: `bridge-approval-policy-mismatch`,
+ *   because a policy under which one command did not ask is not `untrusted`
+ *   whatever the server says about itself;
+ * - no command ran at all: `bridge-preflight-void`, carrying the turn's frames
+ *   verbatim. It is never retried and never reported as a pass.
+ *
+ * An `item/autoApprovalReview` notification in either turn is
+ * `bridge-auto-reviewer-active` and ends the run, after one
+ * `audit.question_preempted` is appended for it (APRV-378): the moment
+ * something other than this gate answered a question this gate exists to ask is
+ * the moment this project most wants in the log.
+ *
+ * THE PROBE'S OWN REQUEST NEVER REACHES THE GATE. It is declined immediately,
+ * as an observation. Routing it through `decideHarnessCall` would register an
+ * action and could put `true` on a human's phone at every bridge start, and a
+ * preflight that spends a person's attention is not a harmless one.
+ *
+ * WHAT A PASS MEANS, exactly: one question reached this client unanswered by
+ * anything else. It is not a proof that the auto-reviewer is off for every
+ * question, and nothing here says that it is.
+ *
+ * ## One at a time, on purpose
+ *
+ * The gate's wait is synchronous, so while one question is being decided this
+ * process is not reading frames. That is the fail-closed direction: frames
+ * queue and are answered in arrival order, and a second request cannot be
+ * answered from a decision made about the first. The observed protocol asks one
+ * question at a time (the turn does not move past an unanswered one).
+ *
+ * ## Limitations stated rather than implied
+ *
+ * An OPEN GATE WINDOW is not honoured here. The hook's bypass prints a hook
+ * verdict and appends a record shaped for the hook; wiring it into this
+ * transport is more surface than this task carries, and ignoring it is the
+ * strict direction — a window widens authority, and this verb simply does not
+ * widen. An operator who opens a window and expects this verb to fall through
+ * will find it still asking.
+ */
+import { hookScope, type HarnessVerdict } from "./hook.js";
+import type { Streams } from "./main.js";
+/**
+ * The approval policy this verb starts a thread under (`untrusted` on the
+ * wire).
+ *
+ * `UnlessTrusted` is the only variant under which every command asks
+ * (`docs/codex-app-server-bridge.md`, question 5), and `unless-trusted` is
+ * REFUSED by the server: the accepted spelling is `untrusted`, established by
+ * the 2026-09-18 probe. There is no flag: a session gating an unknown fraction
+ * of itself is the thing this pin exists to prevent, and an operator who could
+ * pass `on-request` would have exactly that session (APRV-366).
+ */
+export declare const APPROVAL_POLICY = "untrusted";
+/** The sandbox posture the thread starts under. */
+export declare const SANDBOX = "read-only";
+/**
+ * The decision words this verb will send, most literal first.
+ *
+ * `accept`/`decline` are the item-based API's spelling and `approved`/`denied`
+ * the legacy one. The session-wide and amendment-carrying variants are absent
+ * from the accept list, and `cancel`/`abort` from the decline list, for the
+ * reasons in this module's header. A value this runtime does not name is never
+ * sent, however loudly the server advertises it.
+ */
+export declare const ACCEPT_WORDS: readonly ["accept", "approved", "approve", "allow"];
+export declare const DECLINE_WORDS: readonly ["decline", "denied", "deny", "reject"];
+/** One of the four spellings of yes this verb will send. */
+export type BridgeAcceptWord = (typeof ACCEPT_WORDS)[number];
+/** One of the four spellings of no. */
+export type BridgeDeclineWord = (typeof DECLINE_WORDS)[number];
+/**
+ * Everything this verb can put in a `decision` field, as a type (APRV-367).
+ *
+ * The list is the whole vocabulary: eight spellings of two words. A value
+ * outside it is a TYPE ERROR at every point the reply is built, which is the
+ * half of the rule a reviewer cannot forget to check, and it is refused again
+ * at runtime by {@link encodeDecision}, which is the half that survives a
+ * caller with an `any` in it.
+ */
+export type BridgeDecisionWord = BridgeAcceptWord | BridgeDeclineWord;
+/** The two things this verb ever means, whatever the server calls them. */
+export type BridgeOutcome = "accept" | "decline";
+/** Is this one of the eight words? The runtime face of {@link BridgeDecisionWord}. */
+export declare function isBridgeDecisionWord(value: unknown): value is BridgeDecisionWord;
+/**
+ * The reply payload for one word: the ONE place a decision becomes bytes.
+ *
+ * `null` for anything this runtime does not name. The types make such a value
+ * unconstructible, so this is the defence against the code changing out from
+ * under the types rather than against any input a server can send: no
+ * `availableDecisions` list can reach it, because {@link chooseDecision} only
+ * ever returns a member.
+ *
+ * The caller answers `null` by sending a DECLINE, and that is the whole
+ * reasoning: the only safe substitute for a word you cannot name is no. It gets
+ * no refusal code of its own, because a code in a closed union that no input
+ * can produce is a string a second implementation cannot exercise and would
+ * have to take on trust.
+ */
+export declare function encodeDecision(word: string): {
+    decision: BridgeDecisionWord;
+} | null;
+/**
+ * Every refusal this verb can answer with that is NOT a gate verdict, closed
+ * and machine-readable (SPEC §11.1 invariant 7).
+ *
+ * A gate verdict carries the gate's own code (`hook-class-human-only`,
+ * `hook-rejected`, `hook-timeout`, and the rest); these are the refusals the
+ * bridge reaches on its own, before or instead of asking.
+ */
+export declare const BRIDGE_REFUSAL_CODES: readonly [
+/** A file-change request whose content this verb cannot produce (APRV-363). */
+"bridge-file-change-unbound", 
+/** A server request this verb has no reading for. */
+"bridge-unknown-request", 
+/**
+ * A file-change request whose item had already COMPLETED when it arrived
+ * (APRV-379).
+ *
+ * Distinct from `bridge-file-change-unbound`, which says the content could
+ * not be produced. Here the content was produced: the `item/started` frame is
+ * held, the item id correlates, and the change set is right there. What is
+ * wrong is the ORDER. `item/completed` for that item arrived before the
+ * question about it did, and a change that finished before it was asked about
+ * is not a change this client is in a position to decide. Answering yes would
+ * put a grant in the log for an effect that had already happened, and
+ * answering the ordinary no would tell an operator to go and stop something
+ * that is over.
+ *
+ * The repairs differ, which is why the codes do: an unbound change is a
+ * correlation that did not happen and points at this client or at a protocol
+ * that changed shape, and this one points at a session whose approval policy
+ * is not the one it was pinned to, or at a server that reordered its frames.
+ */
+"bridge-file-change-already-completed", 
+/**
+ * An exec request whose command string names no argv this client can bind
+ * (APRV-362).
+ *
+ * Distinct from `bridge-request-unbound`, which says a field is MISSING. This
+ * one says the field arrived and could not be read as the rendering of an
+ * argv: an unterminated quote, a bare double quote, a trailing backslash, or
+ * whitespace no join produces. The repairs differ, which is why the codes do:
+ * a missing `cwd` is a server that changed shape, and this is a command
+ * string that did not come from joining the words that will run.
+ */
+"bridge-command-unbound", 
+/** An exec request carrying no command string, or no cwd. */
+"bridge-request-unbound"];
+export type BridgeRefusalCode = (typeof BRIDGE_REFUSAL_CODES)[number];
+/**
+ * Every way this verb STOPS a session instead of answering a question
+ * (APRV-366), closed and machine-readable.
+ *
+ * A separate array from {@link BRIDGE_REFUSAL_CODES}, and deliberately not a
+ * member of it. Those are answers: one approval request declined, the turn
+ * carrying on. These end the run before or instead of a turn, because the
+ * session could not be established as the kind of session this verb is willing
+ * to sit in front of. The conformance union `bridge_refusal_codes` is
+ * documented as "every way the bridge can decline an app-server approval
+ * request", so a stop code inside it would describe a different boundary, which
+ * is the reasoning that kept these out of `hook_deny_codes` too.
+ *
+ * The process exit for both is {@link EXIT_IO}, as it is for every other
+ * protocol stop here: the exit codes are frozen public API and a session that
+ * could not be started is not a new number. The code below is the distinct part
+ * a caller branches on.
+ */
+export declare const BRIDGE_STOP_CODES: readonly [
+/**
+ * The server refused `thread/start`, so no thread exists and the approval
+ * policy this verb requires was never established. The server's own error is
+ * carried verbatim in the detail, which is where a refusal of the policy
+ * VALUE shows up (the 2026-09-18 probe's `unknown variant \`unless-trusted\`,
+ * expected one of \`untrusted\`, \`on-request\`, \`granular\`, \`never\``).
+ */
+"bridge-thread-start-refused", 
+/**
+ * The server started a thread and reported an effective approval policy that
+ * is not {@link APPROVAL_POLICY}. Under any other variant an unknown fraction
+ * of the session never produces a question at all, so "this client decided
+ * every question it was asked" would be true and would mean nothing.
+ */
+"bridge-approval-policy-mismatch", 
+/**
+ * An `item/autoApprovalReview` notification arrived, in the preflight turn or
+ * in the real one (APRV-364).
+ *
+ * Codex carries a server-side auto-reviewer that can resolve an approval with
+ * a model call BEFORE the client path runs, and tells the client afterwards
+ * through these notifications (`docs/codex-app-server-bridge.md`, question
+ * 3). A session with a reviewer in front of the gate is a session whose
+ * silence means nothing: the questions this client was not asked are
+ * indistinguishable from questions nobody wanted to ask. So the run stops
+ * rather than gating whatever is left over.
+ *
+ * It leaves a RECORD since APRV-378: one `audit.question_preempted`,
+ * appended through the real append path before the stop, naming the source,
+ * the question as Codex identified it, and the verdict the reviewer reached
+ * where the notification stated one. The write is best-effort and the stop
+ * does not depend on it; a failure to append is reported on stderr beside
+ * the stop rather than swallowed.
+ */
+"bridge-auto-reviewer-active", 
+/**
+ * The preflight turn ran no command at all, so the probe established nothing
+ * (APRV-364).
+ *
+ * The preflight is a prompt, and a model is free to answer a prompt in prose.
+ * When that happens no approval request arrives AND no command executes, and
+ * the fact AC1 wants — that a command reached this client as a question —
+ * was not observed. Reporting it as a pass would be reporting a verdict
+ * nobody established, which is the APRV-359 lesson; reporting it as the
+ * policy mismatch would blame a healthy session for a model's choice of
+ * words. So it is its own code, the report carries the turn's frames
+ * verbatim, and nothing is retried: an operator runs the verb again.
+ */
+"bridge-preflight-void"];
+export type BridgeStopCode = (typeof BRIDGE_STOP_CODES)[number];
+/**
+ * Where the report's claim about the approval policy COMES FROM (APRV-364).
+ *
+ * APRV-366 wrote this as a boolean, and a boolean could say only that some
+ * frame echoed the pin back. The preflight probe establishes the same thing a
+ * different way, by watching what happens to one command, and the two are not
+ * the same strength of evidence: an echo is the server describing itself, and
+ * an observation is a thing that happened. A reader who is told `true` cannot
+ * tell them apart, so the field names its source instead.
+ *
+ * - `unconfirmed` — nothing has confirmed the pin. Where every run starts, and
+ *   where a run that stopped before the probe finished stays.
+ * - `reported` — a server frame named the pinned policy as the effective one.
+ *   The observed 0.155.0 server names none, so this is rare in practice.
+ * - `observed` — a probe command produced an approval request that reached
+ *   this client. THE HONESTY LINE, and it is narrow on purpose: it proves that
+ *   ONE question reached this client unanswered by anything else. It is not a
+ *   proof that the auto-reviewer is off, and no code or document here may say
+ *   that it is.
+ */
+export declare const BRIDGE_PIN_SOURCES: readonly ["unconfirmed", "reported", "observed"];
+export type BridgePinSource = (typeof BRIDGE_PIN_SOURCES)[number];
+/**
+ * The thread this verb started, as the report records it (APRV-366).
+ *
+ * `requested` is what went on the wire, `effective` is what the server said
+ * about it, and `confirmed` is the difference between the two: a server that
+ * echoes the policy back proves the pin, and one that says nothing leaves this
+ * client able to claim only that it asked. That distinction is recorded rather
+ * than smoothed over, because a report that said "untrusted" for both cases
+ * would be asserting something no frame carried.
+ *
+ * `confirmed` widened from a boolean to a {@link BridgePinSource} in APRV-364,
+ * when the probe gave it a second and stronger way to be true.
+ */
+export interface BridgeThreadRecord {
+    id: string | null;
+    cwd: string;
+    requested: {
+        approvalPolicy: string;
+        sandbox: string;
+    };
+    effective: {
+        approvalPolicy: string | null;
+    };
+    confirmed: BridgePinSource;
+}
+/**
+ * The one command the preflight turn asks for (APRV-364).
+ *
+ * Chosen for having no effect: it writes nothing, reads nothing, prints
+ * nothing, and exits zero. The point of the probe is the QUESTION it raises,
+ * and a probe whose command mattered would be a probe an operator had to think
+ * about before running.
+ */
+export declare const PROBE_COMMAND = "true";
+/**
+ * The preflight prompt, written to leave a model as little room as a prompt can
+ * (APRV-364).
+ *
+ * It cannot leave none, which is why {@link BRIDGE_STOP_CODES} carries
+ * `bridge-preflight-void`: a model that answers in prose has run no command,
+ * and that outcome is reported rather than guessed at.
+ */
+export declare const PROBE_PROMPT: string;
+/** What the preflight turn established, once it ended. */
+export declare const BRIDGE_PROBE_OUTCOMES: readonly ["pending", "asked", "executed", "void"];
+export type BridgeProbeOutcome = (typeof BRIDGE_PROBE_OUTCOMES)[number];
+/**
+ * The preflight turn, as the report records it (APRV-364).
+ *
+ * `outcome` is the whole of what the probe established:
+ *
+ * - `asked` — an approval request for the probe arrived, so one question
+ *   reached this client. The session continues.
+ * - `executed` — a command ran and no request arrived. A policy under which
+ *   one command did not ask is not `untrusted`, whatever the server said about
+ *   itself, so the run stops under `bridge-approval-policy-mismatch`.
+ * - `void` — no command ran at all, so nothing was established. The run stops
+ *   under `bridge-preflight-void` and `frames` carries the turn verbatim.
+ * - `pending` — the turn has not ended. Only ever seen in a report that
+ *   stopped for some other reason first.
+ */
+export interface BridgePreflightRecord {
+    turnId: string | null;
+    /** The command the prompt named: {@link PROBE_COMMAND}. */
+    command: string;
+    outcome: BridgeProbeOutcome;
+    /**
+     * The word sent on the probe's own approval request, when one arrived.
+     *
+     * Always a decline. The probe is an observation, and a probe this client
+     * approved would be a probe that ran.
+     */
+    decision: BridgeDecisionWord | null;
+    /**
+     * Every frame the preflight turn produced, verbatim, present ONLY on the
+     * void stop.
+     *
+     * On a void there is nothing else to show: the stop says a fact could not be
+     * established, and the frames are the whole of the evidence for why. On any
+     * other outcome they are noise, and a report that always carried them would
+     * bury the line that matters.
+     */
+    frames?: unknown[];
+    /** The turn's own error, when `turn/failed` ended it. */
+    error?: unknown;
+}
+/**
+ * The effective approval policy a server frame reports, or `null` when it
+ * reports none.
+ *
+ * The locations are a documented short list rather than a generic walk: this
+ * value can STOP a session, so it is read from places whose meaning is known,
+ * and a stray `approvalPolicy` nested inside some unrelated structure must not
+ * be able to end a run. The observed 0.155.0 server echoes none of them, which
+ * is why an absent value is not itself a stop.
+ */
+export declare function effectiveApprovalPolicy(value: unknown): string | null;
+/** One answered question, for the report and for the tests. */
+export interface BridgeAnswer {
+    method: string;
+    /** The server's own id for the request, echoed on the reply. */
+    id: unknown;
+    /** `accept` or `decline`, as this verb decided it. */
+    outcome: BridgeOutcome;
+    /**
+     * The word actually sent: one of the eight this runtime names, chosen to
+     * match what the request advertised (APRV-367). Its TYPE is the vocabulary,
+     * so a row saying `acceptForSession` cannot be constructed here.
+     */
+    decision: BridgeDecisionWord;
+    /** Where that word came from: the request's own list, or this verb's fallback. */
+    decisionSource: "advertised" | "fallback";
+    /** The gate's code, or a {@link BRIDGE_REFUSAL_CODES} entry. `null` on an accept. */
+    code: string | null;
+    /** The gate's reason or the refusal's detail, for the operator. */
+    detail: string;
+}
+/**
+ * The decision words a request says are legal, if it says.
+ *
+ * Walked generically rather than read from one key path, so a renamed field of
+ * the same shape still answers. This is the server describing its own
+ * vocabulary, which is the one thing a client should never pin.
+ */
+export declare function advertisedDecisions(params: unknown): string[];
+/**
+ * The word to send for this outcome, and where it came from (AC4).
+ *
+ * An advertised word wins, matched case-insensitively and NEVER by prefix, so a
+ * server that offers `acceptWithExecpolicyAmendment` is not read as offering
+ * `accept`: an amendment carries terms nobody approved. A request advertising
+ * nothing gets this verb's own first word, and the report says `fallback` so
+ * the choice is visible rather than assumed.
+ *
+ * What it returns is this runtime's own spelling of the matched word rather
+ * than the server's (APRV-367). That is the point of the type: a
+ * {@link BridgeDecisionWord} has eight inhabitants, all of them named here, so
+ * no path through this function can produce a word this project did not choose
+ * to be able to send. The two spellings differ only in letter case, since the
+ * match is case-insensitive equality with one of the eight.
+ */
+export declare function chooseDecision(params: unknown, outcome: BridgeOutcome): {
+    decision: BridgeDecisionWord;
+    decisionSource: "advertised" | "fallback";
+};
+/**
+ * The exec request's command, as BOTH the words that will run and the string
+ * that renders them (APRV-362).
+ *
+ * ## Which API, and why the string has to be un-joined
+ *
+ * The two live shapes differ in the one way that matters. The legacy
+ * `execCommandApproval` sends `command` as an argv array, which is what the
+ * kernel receives. The item-based `item/commandExecution/requestApproval` sends
+ * it as a single string, produced by `shlex_join` over that same argv
+ * (`docs/codex-app-server-bridge.md`, question 1). This verb drives the
+ * ITEM-BASED API, so the string is what it must consume, and the decision the
+ * task asked for is settled by which API the bridge speaks rather than by
+ * preference: the legacy array is still read, because a request in that shape
+ * is a request this client can answer, but it is not the path in use.
+ *
+ * Consuming the string means un-joining it. A classifier handed the rendering
+ * and never the words is classifying its own re-parse, and the gap between the
+ * two is where an approval could authorize words nobody read. So both are
+ * produced here, both reach the registered payload, and a reader can see the
+ * one against the other instead of being asked to trust that they agree.
+ *
+ * ## What this refuses, and what it deliberately does not
+ *
+ * A string that is not readable as a join — an unterminated quote, a bare
+ * double quote, a trailing backslash, or separation no join emits — is refused
+ * with `bridge-command-unbound`. So is an argv this runtime cannot render and
+ * read back unchanged, which is unreachable for a correct {@link shlexJoin} and
+ * checked anyway, because the cost is one pass over a short string and the
+ * failure it guards against is binding words nobody will run.
+ *
+ * It does NOT demand that {@link shlexJoin} reproduce the received bytes. That
+ * would pin the counterpart's quoting predicate, which this repository has no
+ * record of: the probe captured one command string and it is consistent with
+ * every candidate. A join written for shell safety quotes more than this one
+ * does, so demanding byte equality would refuse ordinary traffic on a guess.
+ * What is demanded instead is the part that is checkable without knowing which
+ * characters the counterpart chose to quote, and the rest is recorded.
+ *
+ * `proposedExecpolicyAmendment` is deliberately not read, though the task names
+ * it as a candidate second source. The 2026-09-18 observation records that the
+ * field was PRESENT and records nothing about its shape, and a comparison
+ * written against a guessed shape silently matches nothing, which is worse than
+ * the check it pretends to be. It becomes usable once a probe captures it.
+ */
+export type BoundCommand = {
+    ok: true;
+    command: string;
+    argv: string[];
+    source: "rendering" | "argv";
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function bindCommand(params: unknown): BoundCommand | null;
+/**
+ * The turn a frame belongs to, where it names one (APRV-364).
+ *
+ * The preflight and the real turn are told apart by this value, and a frame
+ * that names no turn is decided by which turn is running instead. Both
+ * spellings are read because the protocol has used both casings elsewhere and
+ * neither reading can widen anything: a turn id is only ever used to decide
+ * which of two phases a frame belongs to.
+ */
+export declare function turnIdOf(params: unknown): string | null;
+/**
+ * Is this method one of Codex's auto-approval-review notifications (APRV-364)?
+ *
+ * The recorded names are `item/autoApprovalReview/started` and
+ * `item/autoApprovalReview/completed`
+ * (`docs/codex-app-server-bridge.md`, question 3). The match is on the
+ * SUBSTRING rather than on those two exact names, case-folded, because a
+ * reviewer notification this runtime failed to recognise would be a session
+ * that ran with a reviewer in front of the gate: over-matching costs a stop
+ * that an operator can read and re-run, and under-matching costs the whole
+ * point of the check.
+ */
+export declare function isAutoReviewNotification(method: string): boolean;
+/**
+ * The verdict an auto-review notification states, or `null` (APRV-378).
+ *
+ * Read from a short list of named places rather than by a generic walk, for the
+ * reason {@link effectiveApprovalPolicy} is: this value goes into the log as
+ * another party's decision, and a string picked up from some unrelated
+ * structure would be this runtime putting words in their mouth. `null` is
+ * recorded as an ABSENT verdict, never as a default one.
+ */
+export declare function autoReviewVerdict(params: unknown): string | null;
+/**
+ * Does this notification say a COMMAND was executed (APRV-364)?
+ *
+ * The one reader in this file written against a shape nobody recorded in full.
+ * The 2026-09-18 vocabulary carries `item/started` and `item/completed`, and it
+ * does not record the item object they carry, so this looks for an item whose
+ * type reads as a command execution, or, failing that, for an item carrying a
+ * `command` string.
+ *
+ * That is a guess, and the reason it is an acceptable one is the direction it
+ * fails in. This value only ever chooses BETWEEN TWO STOPS: a preflight turn
+ * where a command ran without asking stops under
+ * `bridge-approval-policy-mismatch`, and one where nothing ran stops under
+ * `bridge-preflight-void`. A guess that misses turns the first into the
+ * second; it can never turn either into a pass, because a pass needs an
+ * approval request to have ARRIVED, which is a frame this client was handed
+ * rather than one it went looking for. The void report carries the frames
+ * verbatim, which is also how the real item shape gets recorded here at last.
+ */
+export declare function namesCommandExecution(params: unknown): boolean;
+/** What the verb was asked to do, once the flags are read. */
+interface BridgePlan {
+    logPath: string;
+    root: string;
+    options: ReturnType<typeof hookScope>["options"];
+    actor: string;
+    workspace: string;
+    prompt: string;
+    waitMs: number;
+    intervalMs: number;
+    serverCommand: string;
+    serverArgs: string[];
+    json: boolean;
+}
+/**
+ * Decide one exec approval request through the gate (AC2, AC3).
+ *
+ * Exported for the tests, which drive it without a server so the DECISION can
+ * be asserted apart from the transport.
+ */
+export declare function decideExecRequest(streams: Streams, plan: BridgePlan, params: unknown): {
+    verdict: HarnessVerdict;
+    threadId: string | null;
+};
+/**
+ * One item this thread's server has told this client about (APRV-379).
+ *
+ * Every `item/started` is recorded, whatever its type, and not only the
+ * file-change ones. That is what lets "an id this client never saw" be told
+ * from "an id that names a `userMessage`": the first is a client that missed a
+ * frame and the second is a server request that points at the wrong thing, and
+ * an operator reading one refusal should not have to guess which happened.
+ */
+export interface RecordedItem {
+    id: string;
+    /** `item.type` as the server spelled it, or `null` where it named none. */
+    type: string | null;
+    /** The change set VERBATIM, for a `fileChange` item that carried one. */
+    changes: readonly unknown[] | null;
+    threadId: string | null;
+    turnId: string | null;
+    /** Has `item/completed` for this item already arrived? */
+    completed: boolean;
+}
+/**
+ * Every item this thread has announced, by item id.
+ *
+ * Kept for the LIFE OF THE THREAD rather than cleared at each turn's end,
+ * because the frame that carries the content and the request that asks about it
+ * are two frames and nothing in the protocol promises they share a turn. It
+ * grows with the number of items a session produces, which is the session's own
+ * size; a bridge that dropped entries to stay small would be a bridge that
+ * refuses a change it was told about, and the refusal would look exactly like a
+ * protocol it had not caught up with.
+ */
+export type ItemIndex = Map<string, RecordedItem>;
+/**
+ * The change set an `item/started` frame carries for a `fileChange` item, or
+ * `null` (APRV-379).
+ *
+ * The observed shape is an ARRAY of `{path, kind, diff}` under `item.changes`
+ * (`docs/codex-app-server-bridge.md`, question 1). It is read as an array and
+ * carried whole; nothing here looks inside an entry, because the classifier
+ * reads the paths and the payload binds the bytes, and a second reader of the
+ * same material in this module would be a second account of one change.
+ */
+export declare function itemChanges(item: Record<string, unknown>): readonly unknown[] | null;
+/**
+ * Record what an `item/started` or `item/completed` notification says
+ * (APRV-379).
+ *
+ * `item/started` writes the entry, `item/completed` marks it completed and
+ * leaves the recorded content ALONE. Refreshing the change set from the
+ * completion frame would let a server hand this client one change set, be asked
+ * about it, and have a different one in the record afterwards; the frame this
+ * client decides against is the one it was holding when the question arrived.
+ */
+export declare function recordItemFrame(index: ItemIndex, method: string, params: unknown): void;
+/** What the correlation produced, or why it produced nothing. */
+export type Correlation = {
+    ok: true;
+    item: RecordedItem;
+    changes: readonly unknown[];
+} | {
+    ok: false;
+    code: BridgeRefusalCode;
+    detail: string;
+};
+/**
+ * Find the `item/started` frame an item-based file-change request refers to
+ * (APRV-379).
+ *
+ * THE WHOLE RISK OF THIS TASK LIVES HERE. The request names an identifier, the
+ * bytes arrived on another frame, and a correlation that matched the wrong item
+ * would let a grant authorize bytes nobody classified. So every way the two
+ * frames could fail to be about the same change is a refusal, and none of them
+ * is resolved in favour of going ahead:
+ *
+ * - no `item/started` for that id was ever seen: `bridge-file-change-unbound`,
+ *   which is the refusal this verb has answered since APRV-361;
+ * - the id names an item that is not a `fileChange`: same code, its own detail.
+ *   An id that points at a `userMessage` is a request this client has no
+ *   content for, however much content that item has;
+ * - the item carried no readable change set: same code. A `fileChange` frame
+ *   with nothing in `changes` is an identifier again;
+ * - the request names a THREAD or a TURN the frame does not: same code.
+ *   Item ids are server-minted and observed unique, so this should never fire,
+ *   and that is exactly why it is checked rather than assumed. Two frames that
+ *   disagree about which conversation they belong to are not established to be
+ *   about one change, and "should never happen" is the reasoning that lets a
+ *   wrong match through. A frame or a request that names NEITHER field is not
+ *   held to it: absence is not disagreement, and the observed frames carry
+ *   both;
+ * - the item already COMPLETED: `bridge-file-change-already-completed`, for the
+ *   reasons that code carries.
+ */
+export declare function correlateFileChange(index: ItemIndex, params: unknown): Correlation;
+/**
+ * The change map a file-change request carries INLINE, or `null` (APRV-363).
+ *
+ * The LEGACY `applyPatchApproval` carries `fileChanges`, a map of path to
+ * change, on the request itself. There is nothing to correlate and nothing
+ * arrives on another frame, so it is the one file-change shape this verb can
+ * bind: the bytes it decides about are the bytes it was sent.
+ */
+export declare function inlineFileChanges(params: unknown): Record<string, unknown> | null;
+/**
+ * Decide one file-change request, whichever API it arrived on (APRV-363,
+ * APRV-379).
+ *
+ * Through the SAME path an exec request takes: the hook's `decideHarnessCall`,
+ * so the human-only refusal, the loop floor, the unattended guard, the
+ * registration and the wait are one implementation. What differs is the tool
+ * name and the bound material, and the description of both is `cli/hook.ts`'s,
+ * never this module's.
+ *
+ * TWO SOURCES FOR THE CHANGE SET, one decision path. The LEGACY
+ * `applyPatchApproval` carries it inline, so it is read off the request. The
+ * ITEM-BASED `item/fileChange/requestApproval` carries an identifier, so it is
+ * correlated to the `item/started` frame this client recorded, by
+ * {@link correlateFileChange}, which refuses rather than guessing. Either way
+ * what reaches the describer is the change set the server sent, in the shape it
+ * sent it.
+ *
+ * THE DIRECTORY, and the two halves differ here for a recorded reason. The
+ * legacy request carries one (`cwd`, or `grantRoot` for the same purpose) and
+ * is refused without it, exactly as APRV-363 left it. The item-based request
+ * carries neither: `grantRoot` was `null` in both captures and there is no
+ * `cwd` on that shape at all (`docs/codex-app-server-bridge.md`, question 1).
+ * So it falls back to the workspace THIS CLIENT named on `thread/start`, which
+ * is this client's own binding rather than a guess or a server claim, and the
+ * fallback widens nothing: the observed change paths are absolute, the
+ * describer resolves every path against that directory, and one landing
+ * outside it is refused `hook-io` whichever way it was spelled.
+ */
+export declare function decideFileChangeRequest(streams: Streams, plan: BridgePlan, params: unknown, items: ItemIndex): {
+    verdict: HarnessVerdict;
+    threadId: string | null;
+};
+export declare function runCodexBridge(argv: string[], streams: Streams, cwd: string): Promise<number>;
+/** The help text, printed by `approval codex bridge --help`. */
+export declare const CODEX_BRIDGE_HELP: string;
+export {};