approval-md 0.3.0 → 0.4.0

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

@@ -76,8 +76,25 @@ 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.
  *
@@ -166,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", 
 /**
@@ -250,6 +295,32 @@ export declare const HOOK_DENY_CODES: readonly [
  * 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];
@@ -278,12 +349,47 @@ export declare function hookScope(flags: Record<string, string | boolean>, cwd:
  * 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).
      *
@@ -329,6 +435,47 @@ interface HarnessAdapter {
      * 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).
@@ -340,6 +487,19 @@ interface HarnessAdapter {
      */
     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).
  *
@@ -358,6 +518,27 @@ interface HarnessAdapter {
  * 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 {
@@ -500,12 +681,48 @@ export declare function resolveReadRoots(cwd: string, gateRoot: string, declared
  */
 export declare function refineReadScope(result: CommandClassification, roots: readonly string[], cwd: string): RefinedClassification;
 /**
- * The classifier, its context, and all three impure refinements, in the one
+ * 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 three 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
@@ -523,7 +740,75 @@ 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;
@@ -539,6 +824,57 @@ interface HookRun {
     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. */
@@ -755,6 +1091,26 @@ export interface DecideInput {
     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;
     /**
@@ -765,6 +1121,12 @@ export interface DecideInput {
      * 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
@@ -783,5 +1145,11 @@ export interface DecideInput {
  * 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): number;
+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 {};