approval-md 0.2.0 → 0.3.0

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

@@ -72,6 +72,10 @@
  * 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 { Streams } from "./main.js";
 import { type Style } from "./style.js";
 /**
@@ -115,6 +119,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. */
@@ -183,9 +210,221 @@ 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", 
 /** 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.
+ */
+interface HarnessAdapter {
+    kind: HarnessKind;
+    originApp: string;
+    defaultActor: string;
+    shellTool: string;
+    fileTools: readonly string[];
+    /**
+     * 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;
+    /**
+     * 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;
+}
+/**
+ * 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 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 +479,41 @@ 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 classifier, its context, and all three 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 three 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 +523,145 @@ 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;
+interface HookRun {
+    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;
+    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 +733,55 @@ 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;
+/**
+ * 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;
+    /** 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;
+}
+/**
+ * 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): number;
+export {};