approval-md 0.2.0 → 0.4.0

package/dist/src/cli/hook.d.ts

@@ -72,8 +72,29 @@
  * auditor holding the log alone. See `docs/claude-code-hook.md`.
  */
 import { type ClassifiedSegment, type CommandClassification, type ProtectedPathEntry } from "../core/command-class.js";
+import { type GateOptions } from "../core/gate.js";
+import { type HarnessKind } from "../core/harness-version.js";
+import { type HarnessLoopState } from "../core/loop.js";
+import type { EventRecord } from "../core/log.js";
+import { type ReadRecordsResult } from "../core/state.js";
 import type { Streams } from "./main.js";
 import { type Style } from "./style.js";
+/**
+ * How many CONSECUTIVE torn-tail reads the decision wait reads past before it
+ * treats the log as unreadable (APRV-427 review).
+ *
+ * The poll reads the log while other writers append to it: the daemon beside
+ * a CLI hook, and every other hook call beside one run by `approval serve`. An
+ * append is one write on an O_APPEND handle, but a reader on a filesystem that
+ * grows a file a page at a time can see the front of a line before its end, and
+ * the verified read calls that a torn tail. It is a moment in someone else's
+ * write, and the next tick reads the whole line. Treating it as terminal
+ * withdrew a live question and denied `hook-io` because a DIFFERENT call was
+ * mid-append. So a torn read is read again next tick, like a view that lags;
+ * only a tail that stays torn for this many ticks in a row (a crashed write,
+ * which nobody is going to finish) takes the old withdraw-and-deny path.
+ */
+export declare const TORN_TAIL_RETRIES = 5;
 /**
  * How much of the command line goes in the (claimed) summary field.
  *
@@ -115,6 +136,29 @@ export declare const HOOK_DENY_CODES: readonly [
  * rejection: nobody decided anything, so there is nothing to ask again.
  */
 "hook-class-human-only", 
+/**
+ * A `harness.launch.*` class that no rule of this policy names (APRV-354).
+ *
+ * SPEC.md §7 says the family is never inferred autonomous; this is the
+ * stronger reading the family needs, which is that it is never inferred at
+ * all. A launch resolves only under a rule an operator wrote, and a policy
+ * that names neither `harness.launch.*` nor the specific member refuses.
+ *
+ * It exists because of the window the softer reading opens. Before the family
+ * existed, `codex …` and `muse …` were `hook-unclassified`: refused outright.
+ * Letting the new class fall to `defaults.autonomy` would have made every
+ * harness launch grantable by one approval in every project whose defaults
+ * are manual, the moment they upgraded — a capability arriving by upgrade
+ * rather than by decision. What that approval would cover is a whole second
+ * agent whose own actions this gate never sees.
+ *
+ * Distinct from `hook-unclassified`, which says the CLASSIFIER has nothing to
+ * say about the command; here the classifier was clear and the POLICY is
+ * silent. Distinct from `hook-class-human-only`, which is a policy that has
+ * spoken and reserved the class: the repair there is for a person to run the
+ * command, and the repair here is to write a line.
+ */
+"hook-harness-launch-unruled", 
 /** A construct whose effect cannot be read off the text (`bash -c`, `eval`). */
 "hook-opaque", 
 /** The command line could not be tokenized at all. */
@@ -139,8 +183,36 @@ export declare const HOOK_DENY_CODES: readonly [
  * directory, once. Past the grace the hook withdraws it (reason `timeout`),
  * because a question nothing will adopt is a message on a phone that decides
  * nothing.
+ *
+ * **Who withdraws, stated because the deny text used to imply a scheduler
+ * that does not exist (APRV-410).** This process is over when it denies, so
+ * the withdrawal is made by the NEXT gated tool call this actor makes, from
+ * the sweep at the top of every gated invocation. It cannot be anyone else: a
+ * withdrawal is the requester's own (APRV-106 rule 1, `not-requester`), the
+ * gate refuses a `system:` withdrawal outright, and the event schema binds
+ * the one `system:` withdrawal that exists to `policy-drift` and to nothing
+ * else (APRV-235). So a session that denies here and then makes no further
+ * gated call leaves the question pending until the TTL, and a decision on it
+ * lands as an ordinary grant. What stops that grant authorizing anything is
+ * the other half of APRV-410: a retry past the grace does not carry it
+ * (`findHarnessCarry`), so it asks again.
  */
 "hook-timeout", 
+/**
+ * The harness ceiling this hook was told it runs under leaves no window a
+ * human could answer in (APRV-423).
+ *
+ * `--harness-cap` (or the harness's own documented maximum) at or below
+ * `HARNESS_CAP_MARGIN_MS` means the question would lapse at the instant it
+ * was asked: the request must end a margin before the harness kills the
+ * process that opened it, and there is no room left for the asking. Nothing
+ * is registered, nothing is requested and nobody's phone lights up. The
+ * repair is a configuration change — raise the harness entry's timeout, or
+ * state the real one — and it is a refusal rather than a silent widening
+ * because a hook that quietly ignored its own ceiling would be back to
+ * recording grants on calls nobody holds.
+ */
+"hook-harness-cap-too-short", 
 /** The gate refused intake; the gate's own code follows a colon. */
 "hook-gate-refused", 
 /**
@@ -183,9 +255,357 @@ export declare const HOOK_DENY_CODES: readonly [
  * merges do not reconcile hash chains (APRV-101).
  */
 "hook-log-unreachable", 
+/**
+ * The harness does not tell this hook where the call will run, so no verdict
+ * over the visible bytes can bind the action (APRV-311, native evidence in
+ * APRV-310 v6/v7).
+ *
+ * Native Codex 0.152.1 honours a per-call Bash working directory that appears
+ * in no field of the event: `tool_input` carries `command` alone, and the
+ * event cwd and the hook process cwd both stay at the session root. A
+ * decision over `{command, session root}` would therefore authorize different
+ * bytes from the `{command, effective directory}` the harness executes, and a
+ * relative path in an approved command can name a protected organ in a
+ * directory the classifier never saw.
+ *
+ * Distinct from `hook-io`, which this used to borrow, and the distinction is
+ * the repair. `hook-io` says THIS event was malformed and a well-formed one
+ * would be answered; this says every event of this shape is refused on this
+ * harness version, and the fix is a harness contract that exposes the
+ * effective execution directory, not a retry, a policy edit, or an open
+ * window. Nothing appends on this path and no gate lifecycle opens.
+ */
+"hook-unsupported-execution-context", 
+/**
+ * The session names a Contributor-tier model, so every tool call is refused
+ * (APRV-350).
+ *
+ * Meta sells a Contributor variant of the Muse Spark family that "trades a
+ * lower price for permission to train on your prompts and completions". A
+ * session on one discloses every byte it reads, so the refusal is above the
+ * policy: no class resolution and no grant widens it, and an absent or
+ * unrecognised `model` is refused for the same reason an unparseable event is.
+ *
+ * Distinct from `hook-class-human-only`, which says a HUMAN must do this
+ * action; this says nothing may do it in this session, and the repair is to
+ * change the model in Muse's picker rather than to ask anybody. Distinct from
+ * `hook-io` because the event was perfectly well formed.
+ *
+ * What it cannot do is stated wherever it is documented: it stops tool calls,
+ * and it cannot recall a prompt the model has already been sent.
+ */
+"hook-muse-contributor-model", 
+/**
+ * A Hermes Agent `execute_code` call, refused before anything else looks at
+ * it (APRV-398).
+ *
+ * The tool takes a `code` string and runs it in-process. There is no path, no
+ * argv and no working directory: nothing the classifier reads exists in the
+ * call, so no class can be resolved and no payload can bind what will happen.
+ * A verdict over `{code}` would authorize a program this runtime never
+ * parsed, which is the same hole `hook-opaque` closes for `bash -c` and the
+ * same one `hook-unsupported-execution-context` closes for a command whose
+ * directory is invisible. SPEC.md §11.1 says ambiguity resolves to the
+ * stricter path, and the strictest honest answer to "may I run this arbitrary
+ * program" is no.
+ *
+ * Distinct from `hook-opaque`, and the distinction is the repair. That one
+ * says a command line carried a construct the classifier could not read, and
+ * the fix is to write the command differently. This one says the TOOL has no
+ * readable surface at all on this harness, so there is no spelling of an
+ * `execute_code` call that would be answered differently: the repair is to do
+ * the work through the shell tool, where the words are visible and the
+ * classifier can price them, or through `approval run` with a granted token.
+ *
+ * Distinct from `hook-unclassified`, which says the classifier had nothing to
+ * say about bytes it could see. Here there are no bytes to see.
+ */
+"hook-hermes-execute-code-unbound", 
 /** Malformed hook input, or a log/filesystem fact that stopped the check. */
 "hook-io"];
 export type HookDenyCode = (typeof HOOK_DENY_CODES)[number];
+/** Where the hook reads policy from and appends to, resolved together. */
+export interface HookScope {
+    logPath: string;
+    /** The directory `logPath` sits under, named in the unreachable-log detail. */
+    root: string;
+    options: GateOptions;
+}
+/**
+ * Policy and log, resolved from the same root (APRV-101).
+ *
+ * Before this, `--dir` scoped only the policy and the log was resolved from the
+ * process cwd, so a hook invoked with `--dir <primary>` from an agent worktree
+ * read the primary's policy and wrote the worktree's copy of the log: a
+ * dead-end chain that forks from the real one. Explicit flags still win
+ * (`--policy` for the policy, `--log` for the log); otherwise both follow
+ * `--dir`, and with no flags at all both follow the primary checkout.
+ */
+export declare function hookScope(flags: Record<string, string | boolean>, cwd: string): HookScope;
+/**
+ * Which harness JSON envelope to print. Never `ask`.
+ *
+ * One definition since APRV-227, in `core/harness-version.ts`: the set of
+ * harnesses this runtime speaks a protocol for is the same set it knows a
+ * binary name for, and two copies of it would be two lists to drift.
+ */
+/**
+ * What a harness's own non-shell, non-file tool asks for (APRV-445).
+ *
+ * `gated` names the class the call is judged under and the headline the
+ * approver reads; the payload is always the WHOLE call (`{tool, input}`), so a
+ * grant binds every argument the harness will act on. `read` is a call that
+ * touches nothing and is allowed without a record, exactly as an in-scope read
+ * tool is. A rule returns `null` for a tool it does not know, and that tool
+ * keeps the not-a-gated-tool allow every unknown tool has.
+ */
+type ToolRuleVerdict = {
+    kind: "gated";
+    cls: string;
+    headline: string;
+} | {
+    kind: "read";
+    reason: string;
+};
+/**
+ * The ceiling a harness puts on its hook process, in milliseconds, or `null`
+ * (APRV-423): the operator's stated `--harness-cap` clamped to the adapter's
+ * contractual maximum, or, with nothing stated, the adapter's documented
+ * default, falling back to that maximum.
+ *
+ * Exported so `approval serve` computes the same number the hook will before
+ * it hands the call to a thread (APRV-427 review): the budget a queued call
+ * has left is this less the time it has waited.
+ */
+export declare function effectiveHarnessCapMs(adapter: Pick<HarnessAdapter, "capCeilingMs" | "capDefaultMs">, statedCapMs: number | null): number | null;
+interface HarnessAdapter {
+    kind: HarnessKind;
+    originApp: string;
+    defaultActor: string;
+    shellTool: string;
+    fileTools: readonly string[];
+    /**
+     * The harness's own tools that carry a side effect of their own, by name and
+     * arguments (APRV-445). Consulted after the shell, file and read tools, for
+     * the calls none of those owns.
+     */
+    toolRules?: (toolName: string, toolInput: Record<string, unknown>) => ToolRuleVerdict | null;
+    /**
+     * Tools that READ a named path (APRV-347).
+     *
+     * Parallel to `fileTools` and answered by a parallel gate. The two lists
+     * differ in what an empty entry means: a file tool with no path is a tool
+     * call this runtime does not understand, while a read tool with no path is
+     * the ordinary spelling of "read the workspace" and keeps the
+     * not-a-gated-tool `allow` it has always had.
+     */
+    readTools: readonly string[];
+    /** Include the native tool name in the bytes a grant binds. */
+    bindToolName?: boolean;
+    /**
+     * Read `toolName`/`toolInput`/`sessionId` as well as the snake_case
+     * spellings (APRV-243).
+     *
+     * Grok Build's PreToolUse envelope is Claude Code's with camelCase keys.
+     * Opt-in per adapter rather than tolerated everywhere: a Claude Code event
+     * that arrived with the wrong spelling is a malformed event, and the strict
+     * answer to a malformed event is the deny that `parseHookInput` already
+     * produces.
+     */
+    camelCaseEnvelope?: boolean;
+    /**
+     * Tools the harness fires for its OWN bookkeeping, answered and never gated
+     * (APRV-350).
+     *
+     * Muse Code fires `PreToolUse` and `PostToolUse` for `submit_reminder_decision`
+     * continuously: 100 of the 139 events in the live capture were that one tool.
+     * It records a self-assessment and touches nothing, so gating it would put a
+     * hundred questions a turn on an approver's phone to authorize the harness
+     * thinking. It is listed rather than inferred, because a tool this runtime
+     * does not recognise must keep falling through to the ordinary path.
+     */
+    passThroughTools?: readonly string[];
+    /**
+     * The `tool_input` key carrying the PER-CALL working directory, when the
+     * harness sends one (APRV-350).
+     *
+     * Muse's `bash` tool carries `workdir`, and it is the directory the command
+     * will actually run in, which is the fact the classifier needs. The top-level
+     * `cwd` is the session's root and can differ. Codex has neither, which is why
+     * its shell arm refuses outright; Claude Code has only the top-level one.
+     */
+    shellCwdKey?: string;
+    /**
+     * The hard ceiling this harness's own contract puts on one hook process, in
+     * milliseconds, or absent when it documents none (APRV-423).
+     *
+     * A CEILING, not a configuration. Hermes states that a `hooks:` entry's
+     * `timeout` may not exceed 300 s, so no Hermes entry can outlive that however
+     * it is written, and this runtime may rely on it. Claude Code, Cursor, Grok,
+     * Muse and Codex document a DEFAULT hook timeout and no maximum, so they
+     * carry none: an adapter that guessed a ceiling would either invent a
+     * deadline the harness never imposed, or — worse, and the direction that
+     * actually costs something — guess high and leave the gap APRV-410 falls
+     * through. The operator states the entry they configured with
+     * `--harness-cap`, and the effective cap is the smaller of the two.
+     */
+    capCeilingMs?: number;
+    /**
+     * The ceiling this harness imposes on a hook process when the operator has
+     * stated none, in milliseconds, or absent when the harness's defaults leave
+     * the process unbounded (APRV-423, second review pass).
+     *
+     * Read ONLY when `--harness-cap` is absent, and then it stands in for the
+     * flag: the operator has said nothing, so the runtime assumes the harness is
+     * running as shipped. It is the STRICTEST bound the harness's own defaults
+     * put on the process, because assuming a looser one is APRV-410 with a
+     * fictional deadline: a request judged against a window the harness will not
+     * keep open. On Hermes that is `plugins.hook_callback_timeout`, which bounds
+     * the whole hook dispatch and defaults to 30 s, well under the margin, so a
+     * Hermes hook with no flag is refused `hook-harness-cap-too-short` until the
+     * operator raises that setting and says so. A stated flag replaces this
+     * value (the operator knows what they configured) and is still clamped by
+     * {@link capCeilingMs}, so a stated cap can only shorten the contractual
+     * maximum, never exceed it.
+     */
+    capDefaultMs?: number;
+    /**
+     * How an operator lifts a `hook-harness-cap-too-short` refusal on this
+     * harness, in the harness's own vocabulary (APRV-423, second review pass).
+     * Appended to the deny so the repair names the setting to change rather than
+     * a generic "raise the timeout". Absent adapters get the generic sentence.
+     */
+    capRepair?: string;
+    /**
+     * Refuse every tool call when the envelope names a Contributor-tier model
+     * (APRV-350).
+     *
+     * Meta sells a Contributor variant that "trades a lower price for permission
+     * to train on your prompts and completions". A session on one is a session
+     * whose every read is disclosed, so the adapter refuses regardless of what
+     * the policy would otherwise allow. See {@link contributorModelRefusal}.
+     */
+    contributorModelGuard?: boolean;
+}
+/**
+ * Hermes Agent's event names, which are its own and not Claude Code's
+ * (APRV-398).
+ *
+ * snake_case, and the VERBS differ too: `pre_tool_call` where every other
+ * harness in this table says `PreToolUse`. That is why they are constants
+ * rather than two more entries in {@link POST_TOOL_EVENTS} — a harness whose
+ * post-event name appeared in that shared list would also accept
+ * `PostToolUse` from an event nobody sent, and the dispatch would answer a
+ * name this harness never uses.
+ */
+export declare const HERMES_PRE_TOOL_EVENT = "pre_tool_call";
+export declare const HERMES_POST_TOOL_EVENT = "post_tool_call";
+/**
+ * Every harness this runtime speaks a hook protocol for, by kind (APRV-358).
+ *
+ * The table is `Record<HarnessKind, HarnessAdapter>` rather than a list of
+ * consts and a switch, and the type is the point: a kind added to
+ * `HARNESS_KINDS` with no adapter beside it fails to compile, so the two lists
+ * cannot drift by forgetting. The subcommand dispatch below reads this map, so
+ * `approval hook <kind>` is answerable for exactly the kinds named here.
+ *
+ * The kinds that are enumerated OUTSIDE this module — the schema's
+ * `payload.harness` enum, the verb registry's `hook` subcommands, the MCP
+ * exclusions, the help — are pinned set-equal to `HARNESS_KINDS` by
+ * `tests/harness-enum.test.ts`, which exists because `grok` shipped an adapter
+ * in APRV-243 and reached none of them. A Grok session's manual-class
+ * registration was refused at the write boundary for eleven days and nothing
+ * failed.
+ */
+export declare const HARNESS_ADAPTERS: Readonly<Record<HarnessKind, HarnessAdapter>>;
+/**
+ * The block directive a harness reads, as bytes, for a refusal raised OUTSIDE
+ * the hook (APRV-421).
+ *
+ * `approval serve` can refuse a hook request before `commandHook` is reached
+ * at all: an oversized body, a credential at the wrong door, a method it does
+ * not answer. Each of those is a refusal by the transport, and a transport
+ * refusal a harness reads as "no verdict" is a harness that runs the command.
+ * So the refusal has to be spoken in the harness's own dialect, and the only
+ * correct source of that dialect is the function that prints it here.
+ *
+ * It renders through {@link deny} for that reason: one construction site per
+ * harness, still never `ask`. The exit code returned is the one the verb would
+ * have carried; a caller may impose a stricter one, and the transport does.
+ */
+export declare function harnessBlockDirective(code: string, detail: string, harness: HarnessKind): {
+    stdout: string;
+    exitCode: number;
+};
+/** The machine-readable code a Hermes `execute_code` call is refused with. */
+export declare const HERMES_EXECUTE_CODE_REFUSAL = "hook-hermes-execute-code-unbound";
+/** The machine-readable code a Contributor-tier session is refused with. */
+export declare const MUSE_CONTRIBUTOR_REFUSAL = "hook-muse-contributor-model";
+export interface HookInput {
+    sessionId: string;
+    /** Whether the event supplied the session id, distinct from the strict unknown bucket. */
+    sessionIdPresent: boolean;
+    cwd: string;
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string | null;
+    /**
+     * `hook_event_name`, verbatim, or `null` when the event carries none
+     * (APRV-145).
+     *
+     * Read at last. Until this, nothing in this module looked at it and
+     * `runHarnessHook` assumed a pre-execution event unconditionally, so an
+     * operator who registered this same command for the post-execution event would
+     * have gated every command a second time and doubled every prompt on the
+     * approver's phone.
+     */
+    hookEventName: string | null;
+    /**
+     * The model the session reports running, or `null` (APRV-350).
+     *
+     * Muse sends it on every event. Read for one purpose only, the contributor
+     * guard, and that guard can only ever refuse: a self-reported field raises
+     * scrutiny and never lowers it (SPEC §11.1). It is never logged, because it
+     * is untrusted third-party text and §11.1 invariant 3 has no provenance
+     * exception.
+     */
+    model: string | null;
+    /**
+     * `tool_response`, when the event carries one as an object.
+     *
+     * Present only on a post-execution event; the pre-execution path never reads
+     * it, because the tool has not run. Its SHAPE is all that is ever read (see
+     * {@link readReportedOutcome}) — never the text inside it.
+     */
+    toolResponse: Record<string, unknown> | null;
+    /** `tool_response` verbatim, including strings, for harness-specific readers. */
+    toolResponseRaw: unknown;
+    /**
+     * `is_interrupt`, the post-execution events' own word for "a person stopped
+     * this" (APRV-303).
+     *
+     * `PostToolUseFailure` carries it beside `error`; `PostToolUse` carries the
+     * same fact as `tool_response.interrupted`. Read only to make an outcome
+     * UNREADABLE, never to establish one, so nothing about it can lower scrutiny.
+     */
+    interrupted: boolean;
+    /**
+     * `version`, when the harness states its own (APRV-227).
+     *
+     * Claude Code's event may carry it; Cursor's does not, and neither did any
+     * Claude Code release before it. So this is a preference and never a
+     * requirement: `core/harness-version.ts` falls back to `<binary> --version`
+     * and then to absence, and a hook that can establish nothing records nothing.
+     *
+     * SELF-REPORTED, and read at all only because it cannot buy the reporter
+     * anything. Nothing in this module branches on it; it reaches exactly one
+     * payload field whose one reader is a doctor row that can only ADD a red
+     * line, so §11.1 invariant 4 holds by construction rather than by care. A
+     * harness that states a false version defeats a check that would have asked a
+     * human to look, and gains no verdict it did not already have.
+     */
+    harnessVersion: string | null;
+}
 /** A classification plus a human-readable note for every segment refined. */
 export interface RefinedClassification {
     result: CommandClassification;
@@ -240,14 +660,77 @@ export declare function resolveScratchRoots(cwd: string, env?: NodeJS.ProcessEnv
  */
 export declare function refineScratchDelete(result: CommandClassification, roots: readonly string[]): RefinedClassification;
 /**
- * The classifier, its scratch context, and both impure refinements, in the one
+ * The read roots this process may vouch for, resolved.
+ *
+ * The gate root is the directory the hook resolved its POLICY from, never the
+ * harness-supplied `cwd`: a scope the subject of the gate could choose is not a
+ * scope (SPEC.md §11.1, self-reported fields never reduce scrutiny). The
+ * scratchpad and temp roots are the ones `resolveScratchRoots` already computes
+ * and already guards, so the two rules cannot disagree about where the agent's
+ * own scratch is. `declared` is `read_scope.roots` out of the loaded policy,
+ * which may only widen this set.
+ */
+export declare function resolveReadRoots(cwd: string, gateRoot: string, declared?: readonly string[]): string[];
+/**
+ * Tighten a `read.shell` segment to `read.file.out_of_scope` wherever the disk
+ * disagrees with the text.
+ *
+ * IMPURE by design and by contract. `roots` empty means the caller asked for no
+ * read scoping at all, and every segment is returned untouched — the same
+ * "absent yields today's answer" the classifier context promises.
+ */
+export declare function refineReadScope(result: CommandClassification, roots: readonly string[], cwd: string): RefinedClassification;
+/**
+ * The roots a write may land in, resolved.
+ *
+ * The scratch roots are the ones `resolveScratchRoots` already computes and
+ * already guards, so this rule and the delete rule cannot disagree about where
+ * the agent's own scratch is. The working directory is the other one, and it is
+ * the root the classifier's own text rule already implies: "a relative
+ * destination is the workspace" means the workspace is wherever the command
+ * runs.
+ *
+ * `cwd` is harness-supplied, and reading a root out of it does not offend
+ * SPEC.md §11.1 invariant 4, because this pass only ever narrows. The baseline
+ * it narrows from is no check at all, so a poisoned `cwd` buys back exactly
+ * today's answer and never a looser one. Compare the read pass, which checks
+ * containment against the GATE root: that pass decides whether a read is in
+ * scope at all, so the scope has to be one the subject cannot choose. This one
+ * only takes an allowance away.
+ */
+export declare function resolveWriteRoots(cwd: string): string[];
+/**
+ * Tighten a `files.write.workspace` segment to the out-of-scope write class
+ * wherever the disk disagrees with the text.
+ *
+ * IMPURE by design and by contract, exactly as the other two passes are. The
+ * class it tightens to is the one `core/command-class.ts` already answers for
+ * an out-of-scope packaging destination rather than a new name: a class no
+ * policy mentions resolves by `defaults.autonomy` (SPEC.md §7), so minting
+ * `files.write.out_of_scope` here would arrive AUTONOMOUS in every deployment
+ * with permissive defaults, which is the one way a tightening pass could
+ * loosen something.
+ *
+ * `roots` empty means the caller asked for no write scoping, and every segment
+ * comes back untouched: the same "absent yields today's answer" the read pass
+ * promises.
+ */
+export declare function refineWriteScope(result: CommandClassification, roots: readonly string[], cwd: string): RefinedClassification;
+/**
+ * The classifier, its context, and all four impure refinements, in the one
  * order every caller must use.
  *
  * `hook classify` printing a different class from the one `hook claude-code`
  * decides would make the explainer a different program (APRV-108's note), and
- * that stays true now there are two refinements in the chain.
+ * that stays true now there are four refinements in the chain.
+ *
+ * `readRoots` is the one argument whose ABSENCE is the loose answer rather than
+ * the strict one (APRV-347), so it is passed explicitly at every call site: an
+ * empty list means "do not scope reads", which is what every caller outside a
+ * resolved gate scope wants and what this classifier did before the field
+ * existed.
  */
-export declare function classifyForHook(command: string, protectedPaths: readonly ProtectedPathEntry[], cwd: string): RefinedClassification;
+export declare function classifyForHook(command: string, protectedPaths: readonly ProtectedPathEntry[], cwd: string, readRoots?: readonly string[]): RefinedClassification;
 /**
  * What the classifier made of a command (APRV-91 #9).
  *
@@ -257,6 +740,264 @@ export declare function classifyForHook(command: string, protectedPaths: readonl
  * that the `json` veto on colour is the answer this process memoizes.
  */
 export declare function renderClassification(result: CommandClassification, json: boolean, st?: Style): string;
+/**
+ * Where a hook invocation stops appending and starts waiting, for a caller that
+ * shares one store with other work in the same process (APRV-427).
+ *
+ * `approval serve` runs many hook calls, verbs and log reads against one store
+ * from one process. Its per-store lock has to cover every stretch in which a
+ * hook call APPENDS (intake, the abandoned-question sweep, register, request,
+ * the spend, the withdrawals) so that no other in-process writer lands between
+ * a check and its append; and it must NOT cover the poll loop, where the hook
+ * only reads the verified log and sleeps, or one question waiting on a human
+ * holds the tenant's whole facade for as long as the human takes.
+ *
+ * So the loop says where it begins and ends. `enterWait` is called once, right
+ * before the first poll, and after it nothing is appended until `leaveWait`
+ * returns. `leaveWait` is called before every append the loop can reach (the
+ * spend on a grant, a withdrawal on a failed read, at the deadline, on a throw
+ * or a signal) and once more when the loop is left by any route, and it may
+ * BLOCK until the caller's lock is held again. Both are idempotent pairs: the
+ * hook never calls `leaveWait` without a matching `enterWait` before it.
+ *
+ * Absent (the CLI, the Codex bridge), both are no-ops and the invocation is
+ * byte-for-byte what it was. The seam decides nothing: no verdict, record or
+ * line depends on it, and the appends it brackets are compare-and-append
+ * either way (SPEC.md §11.1 invariant 5). It only tells an embedding caller
+ * which stretch of the call is safe to run beside other writers.
+ */
+export interface HookWaitSeam {
+    /** The poll loop is about to start: nothing is appended until {@link leaveWait}. */
+    enterWait(): void;
+    /** An append follows, or the loop is over. May block until the caller's lock is held. */
+    leaveWait(): void;
+    /**
+     * The read each poll tick makes. Omitted by every real caller, which gets
+     * `readVerifiedRecords`; it exists so a test can put a torn read in front of
+     * the loop without writing a torn line into a log.
+     */
+    pollRead?: (logPath: string) => ReadRecordsResult;
+    /**
+     * Whether the party this invocation answers has gone away (APRV-427 review).
+     *
+     * `approval serve` sets it when the HTTP client that asked disconnects. Read
+     * on every poll tick, and once more after the lock is re-taken and before a
+     * grant is spent: while it is set, the invocation stops waiting WITHOUT
+     * spending and WITHOUT withdrawing, so the question (or its grant) is left
+     * exactly as a hook-timeout inside the retry grace leaves it, for the
+     * harness's retry to adopt. A grant already spent is not affected: the check
+     * precedes the spend, and nothing after it looks again.
+     */
+    cancelled?: () => boolean;
+    /**
+     * What is LEFT of the harness's ceiling when this invocation begins, in
+     * milliseconds, as the embedding caller measured it (APRV-427 review).
+     *
+     * The harness's ceiling runs from the moment the harness sent the call, not
+     * from the moment this invocation began. `approval serve` may hold a call in
+     * line for a thread, and for the store lock, before the hook's first line
+     * runs; that time is spent out of the same budget. The caller computes the
+     * remainder ONCE, admits the call on it, and hands the same number here, so
+     * the hook judges, waits by and records on the request exactly what the
+     * caller admitted: a call the caller let through never meets
+     * `hook-harness-cap-too-short` a few milliseconds later. It can only
+     * shorten the ceiling the flags give (never lengthen it), and it is omitted
+     * by the CLI, where the process starts when the harness calls.
+     */
+    remainingCapMs?: number;
+}
+interface HookRun {
+    /** APRV-427: the embedding caller's wait seam, or `null` from the CLI. */
+    waitSeam: HookWaitSeam | null;
+    logPath: string;
+    options: GateOptions;
+    actor: string;
+    timeoutMs: number;
+    intervalMs: number;
+    /**
+     * How long a request outlives the wait before this hook takes it back
+     * (APRV-287, `--retry-grace`).
+     *
+     * `core/harness-wait.ts` holds the default and the reasoning. Zero withdraws
+     * at the moment the wait expires, which is what the tests drive.
+     */
+    graceMs: number;
+    /** `defaults.approval_ttl`, or `null` when the policy declares none. */
+    ttlMs: number | null;
+    /**
+     * The ceiling this harness puts on this process, in milliseconds, or `null`
+     * (APRV-423).
+     *
+     * The entry timeout the operator stated with `--harness-cap`, clamped to the
+     * harness's own documented maximum ({@link HarnessAdapter.capCeilingMs}); or,
+     * when no flag was passed, the harness's default bound
+     * ({@link HarnessAdapter.capDefaultMs}, falling back to the ceiling). It is
+     * written onto every request this invocation opens and read back by the gate,
+     * which judges the question against the shorter of it (minus the margin) and
+     * the policy's TTL — so the request ends while this process is still alive to
+     * be told, and the daemon's `approval.expired` lands before the harness gives
+     * up.
+     */
+    harnessCapMs: number | null;
+    /**
+     * Whether {@link harnessCapMs} came from the operator's own `--harness-cap`
+     * (`true`) or was assumed from the adapter's documented defaults (`false`).
+     * A refusal for a cap with no room in it says which, because the repair
+     * differs: a stated cap is a real configuration to raise, an assumed one is
+     * a flag the operator has not passed yet.
+     */
+    harnessCapStated: boolean;
+    /**
+     * The ceiling {@link harnessCapMs} was charged down from, or `null` where
+     * nothing was charged (APRV-427 review). Wording only.
+     */
+    harnessCapCeilingMs: number | null;
+    /** {@link HarnessAdapter.capRepair}, or `null` for the generic sentence. */
+    harnessCapRepair: string | null;
+    /**
+     * How long THIS invocation actually waits, in milliseconds (APRV-423, third
+     * review pass): `timeoutMs`, clamped to what the harness ceiling leaves after
+     * the margin (`harnessCapMs - HARNESS_CAP_MARGIN_MS`) when there is one, and
+     * never below zero.
+     *
+     * The clamp is what closes the adopted-question gap. The too-short refusal
+     * fires only for a question this invocation would OPEN; an invocation whose
+     * every key is adopted (a retry of bytes an earlier, correctly-capped run
+     * asked about) opens nothing, so under a ceiling with no room in it (a Hermes
+     * hook with no `--harness-cap`, assumed 30 s) it would have sat in its poll
+     * loop for the configured wait, been killed at the ceiling, and let the call
+     * proceed on any harness without `fail_closed`. Bounding the wait itself means
+     * the hook always answers before the harness stops listening: a zero wait
+     * reads the verified log once (so a decision already recorded is still
+     * honoured) and then denies `hook-timeout`, leaving the adopted question open
+     * for the retry grace exactly as a wait that ran out would. The adopted
+     * question's OWN deadline is whatever was recorded when it was opened; this
+     * changes nothing about it.
+     */
+    waitMs: number;
+    harness: HarnessKind;
+    originApp: string;
+    /** Exact native command bytes required in a Codex allow's identity update. */
+    codexCommand?: string;
+    /**
+     * The version the hook event stated, or `null` (APRV-227).
+     *
+     * Carried rather than resolved here: resolving it means a `spawnSync` of
+     * `<binary> --version`, and a hook process exists per gated tool call. The
+     * resolution happens at the one place that is about to WRITE a record and
+     * nowhere else, so the pass-through verdict and the autonomous verdict pay
+     * nothing for it. See {@link registrationProvenance}.
+     */
+    eventVersion: string | null;
+    /**
+     * The channel names this policy configures, sorted (APRV-281).
+     *
+     * Read off the policy the caller already loaded, and used for ONE thing: the
+     * line this hook prints when it appends a request, so the agent and the
+     * operator watching its error stream are told where the question went. It
+     * resolves nothing and reaches no verdict. An empty list is a fact worth
+     * printing rather than a default to fill in: a request under a policy that
+     * configures no channel is a question nothing is delivering.
+     */
+    channels: readonly string[];
+}
+/**
+ * The gated half: find what is already open for these bytes, request whatever
+ * is not, wait for the decisions, spend the grants. Returns the exit code of
+ * whatever verdict it printed.
+ *
+ * ## Requests are keyed by bytes, not by invocation (APRV-117)
+ *
+ * The action key is still `hook:<session>:<tool-use id>:<class>` and is still
+ * unique per invocation — what changed is that intake LOOKS for an earlier
+ * request about the same `{command, cwd}` before opening a new one, matching on
+ * the `payload_hash` recorded on `approval.requested`. Three outcomes per class,
+ * decided by `core/gate.ts`'s `findHarnessCarry`:
+ *
+ *  - nothing to carry: register and request, exactly as before;
+ *  - a pending request: **adopt** it — wait out the remainder of this
+ *    invocation's window on somebody else's key, opening nothing. The approver's
+ *    phone never shows two prompts for one command, because there is only ever
+ *    one question;
+ *  - an unspent grant inside the TTL: **carry** it — no wait, no prompt, and
+ *    the grant is spent (once) before the allow is printed.
+ *
+ * ## Why the wait no longer ends in a withdrawal (APRV-106, revised)
+ *
+ * APRV-106 retracted the request when the wait elapsed, because a retried tool
+ * call was a new request with a new key and a late tap therefore authorized
+ * nothing: the human spent attention on a question whose asker had left. The
+ * carryover above removes the premise. A late tap now authorizes the retry, so
+ * the request stays open for the policy's TTL and the timeout says so.
+ *
+ * What still withdraws is every path where nothing can adopt the question: a
+ * SIGTERM or SIGINT (the session is going away), a thrown failure, and an intake
+ * refusal partway through a multi-class command (the command cannot proceed on
+ * any retry, so the classes already opened are noise in a human's queue). The
+ * signal handlers are installed for the duration of the wait ONLY, and removed
+ * in `finally`: a hook process is short-lived and borrowing the harness's
+ * signal disposition for longer than the loop would be a side effect nobody
+ * asked for.
+ */
+/**
+ * What the gate decided about one harness tool call, before anything is printed
+ * (APRV-361).
+ *
+ * {@link gateHarnessCall} produces it and {@link gateAndWait} renders it in the
+ * harness's own dialect. The split exists because a second caller answers in a
+ * protocol rather than on stdout: `cli/codex-bridge.ts` replies
+ * `{id, result: {decision}}` over the app-server's JSON-RPC connection, and it
+ * has to reach that decision through the SAME classify, register, request and
+ * wait this function runs. Two implementations of that sequence would be two
+ * gates, and the second one would be the one nobody reviewed.
+ *
+ * `code` and `detail` are kept apart rather than pre-joined, because the bridge
+ * records the code as a code (§11.1 invariant 7) where the hook prints the pair
+ * as one reason string.
+ */
+export type HarnessVerdict = {
+    permission: "allow";
+    reason: string;
+} | {
+    permission: "deny";
+    code: string;
+    detail: string;
+};
+export declare function gateHarnessCall(streams: Streams, run: HookRun, classes: string[], 
+/**
+ * The bytes the grant binds to: `{command, cwd}` for a Bash call, the change
+ * itself for a file tool (APRV-124). Whatever this is, it is what reaches the
+ * approver's FULL PAYLOAD block, complete — the summary below is a headline
+ * and is the only thing here that may be shortened.
+ */
+payload: unknown, headline: string, 
+/**
+ * The task id this invocation acts under, minted once by the caller
+ * (APRV-139) so the loop-escalation check and the registration it may lead to
+ * name the same task. Deriving it twice would mint two ids whenever
+ * `tool_use_id` is absent and the random fallback runs.
+ */
+task: string, 
+/** The history-rewrite refinement's own words, or `""` (APRV-108). */
+note?: string, 
+/**
+ * The harness streak that floors the SIDE-EFFECTING classes of this
+ * invocation to `manual` (APRV-145, narrowed by APRV-297), or `null` where
+ * policy alone sent it here.
+ *
+ * Passed into `request` as a boolean rather than acted on here, so the floored
+ * action takes the identical path a manual class takes — same records, same
+ * order, same wait — and nothing below knows how it got there. What the STATE
+ * adds (APRV-280) is the deny text: an agent whose commands are all suddenly
+ * on the phone is owed the reason and the way out in the same breath, and
+ * before APRV-280 the nine-minute wait ended in a bare `hook-timeout` that
+ * said neither.
+ *
+ * Since APRV-297 the caller passes `null` for a command whose classes are all
+ * reads, and {@link floorApplies} below carves the read classes out of a mixed
+ * one, so a floor never puts a question about looking on a human's phone.
+ */
+floor?: HarnessLoopState | null): HarnessVerdict;
 /**
  * Every line the counterpart can print, closed and machine-readable (§11.1
  * invariant 7).
@@ -328,4 +1069,87 @@ export declare const REQUIRE_SANDBOX_ENV = "APPROVAL_HOOK_REQUIRE_SANDBOX";
  * invariant 4).
  */
 export declare function sandboxRequirement(segments: readonly ClassifiedSegment[] | undefined, autonomies: readonly string[], env?: NodeJS.ProcessEnv): string | null;
-export declare function commandHook(argv: string[], streams: Streams, cwd: string, readStdin?: () => string): number;
+/**
+ * What {@link decideHarnessCall} needs to reach a verdict (APRV-361).
+ *
+ * Everything here is established by the CALLER: which harness asked, where the
+ * policy and the log are, who is acting, and how long this decision may take.
+ * Nothing in it is authored by the party under oversight beyond `input`, which
+ * is the harness's own event and is treated as such throughout.
+ */
+export interface DecideInput {
+    streams: Streams;
+    input: HookInput;
+    adapter: HarnessAdapter;
+    /** The directory a relative path in the call resolves against. */
+    cwd: string;
+    logPath: string;
+    /** The scope root, named in the unreachable-log detail. */
+    root: string;
+    options: GateOptions;
+    actor: string;
+    timeoutMs: number;
+    intervalMs: number;
+    graceMs: number;
+    /**
+     * The harness's ceiling on this process, in milliseconds, or `null`
+     * (APRV-423). See {@link HookRun.harnessCapMs}. A caller that is not run by a
+     * harness on a timer — `cli/codex-bridge.ts` holds its own connection open —
+     * passes `null` and the policy's TTL governs alone.
+     */
+    harnessCapMs?: number | null;
+    /**
+     * Whether `harnessCapMs` was stated by the operator (`--harness-cap`) rather
+     * than assumed from the adapter's documented defaults (APRV-423, second
+     * review pass). Defaults to `false`; see {@link HookRun.harnessCapStated}.
+     */
+    harnessCapStated?: boolean;
+    /**
+     * The ceiling `harnessCapMs` was charged down from, where an embedding
+     * caller charged time spent before this invocation began (APRV-427 review).
+     * Wording only: a refusal names both, so the operator's stated number is
+     * not reported as the remainder.
+     */
+    harnessCapCeilingMs?: number;
+    /** Exact native command bytes a Codex allow must carry back, where there are any. */
+    codexCommand?: string | undefined;
+    /**
+     * The verified records an open-window lookup already read, or `null`.
+     *
+     * Passed rather than re-read so the floor and the unattended guard are
+     * decided from the same read the window was. A caller that performed no
+     * lookup passes `null`, and both of them read the log themselves.
+     */
+    windowRecords: EventRecord[] | null;
+    /**
+     * Where the wait begins and ends, for a caller that runs this beside other
+     * writers in one process (APRV-427; see {@link HookWaitSeam}). Omitted by
+     * every CLI route, where it is a no-op.
+     */
+    waitSeam?: HookWaitSeam | null;
+}
+/**
+ * Classify, resolve, gate and wait: one harness tool call, from the event to a
+ * verdict (APRV-361).
+ *
+ * Extracted from the hook's own verb so a SECOND caller can reach a decision
+ * through exactly this sequence. `cli/codex-bridge.ts` answers Codex's
+ * app-server approval requests over JSON-RPC rather than on stdout, and the
+ * thing it must not do is re-implement any of what is below: the human-only
+ * refusal, the unruled `harness.launch.*` refusal, the sandbox requirement, the
+ * loop floor, the unattended guard, the autonomous charge, and the register,
+ * request and wait that follow. Two implementations of that sequence would be
+ * two gates, and the second one would be the one nobody reviewed.
+ *
+ * It returns a verdict and prints none. `streams.err` still carries the
+ * progress and withdrawal lines, which are a report rather than a decision.
+ */
+export declare function decideHarnessCall(decide: DecideInput): HarnessVerdict;
+export declare function commandHook(argv: string[], streams: Streams, cwd: string, readStdin?: () => string, 
+/**
+ * APRV-427: where a harness hook's wait begins and ends, for `approval serve`,
+ * which runs the call off its main thread and releases its store lock while
+ * the call polls. Every CLI route omits it. See {@link HookWaitSeam}.
+ */
+waitSeam?: HookWaitSeam | null): number;
+export {};