approval-md 0.1.0 → 0.3.0

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

@@ -0,0 +1,787 @@
+/**
+ * `approval hook` — harness adapters that put the gate in front of the commands
+ * an agent's harness runs directly (APRV-82 Claude Code, APRV-133 Cursor).
+ *
+ * The problem it closes. Until this verb, the runtime gated what went through
+ * `approval run`. Everything the harness executed on its own — `git push`, `gh
+ * pr create`, `npm install`, `curl` — bypassed APPROVAL.md entirely, so the
+ * enforcement of those classes was the prose in CLAUDE.md and an agent's
+ * willingness to read it. That is exactly the AGENTS.md failure SPEC.md §2
+ * critiques, reproduced inside the repository that critiques it.
+ *
+ * As everywhere else in this CLI, **no logic lives here.** Classification is
+ * `core/command-class.ts` (pure, fixture-tested); registration, policy
+ * resolution and intake are `core/gate.ts`; the decision is derived from the
+ * verified log by `core/state.ts`. This file reads one JSON object from stdin,
+ * calls those, and prints one JSON object back.
+ *
+ * Four choices are load-bearing enough to state plainly.
+ *
+ * **It exits 0 with a verdict, or 2 with nothing.** Claude Code reads a hook's
+ * stdout as a decision only on exit 0; a hook that exits 2 is a *block* with the
+ * stderr text as the reason, and any other non-zero code is a non-blocking
+ * error. So every classified or decided outcome — allow and deny alike — is an
+ * exit 0 with `hookSpecificOutput` on stdout, and the only exit 2 is a
+ * misconfigured hook (an unknown flag, a bad identity), where blocking is the
+ * correct failure mode. No new exit code is added to the frozen table.
+ *
+ * **Never `ask`.** The permission decision vocabulary includes `ask`, which
+ * hands the question to the harness's own prompt. Using it would answer an
+ * approval question outside the log: no request, no record, no audit trail, and
+ * a human deciding in a UI the policy never named. The hook allows or denies,
+ * and every deny carries a machine-readable code.
+ *
+ * **Fail closed on every axis.** An unreadable policy, an unreachable log, a
+ * command the classifier cannot read, a wait that times out: all deny. A hook
+ * that fell back to allow when it could not reach the gate would be worst
+ * precisely when it mattered. Since APRV-139 that includes an unattested
+ * policy: a verdict nobody is asked about is checked against the verified log
+ * first, exactly as `core/execute.ts` checks one (see `unattendedGuard`).
+ *
+ * **The harness executes, not the runtime.** The hook decides *before* the tool
+ * runs and never spawns anything, so it never writes an `execution.completed`
+ * or `execution.failed`: the runtime does not run the command and never learns
+ * how it went. It does write one `execution.started`, and only where a verdict
+ * of `allow` rests on a human's grant — that record is the *consumption* of the
+ * grant (APRV-117), which a harness request needs because it mints no token
+ * that could be spent instead. `core/gate.ts`'s `consumeHarnessGrant` is where
+ * that lives and why. What the log records is otherwise the approval lifecycle:
+ * `task.registered`, `approval.requested`, and the human's decision.
+ *
+ * **A decision outlives the invocation that asked for it (APRV-117).** Requests
+ * are matched by the payload hash of `{command, cwd}`, so the answer to "may I
+ * run these bytes, here" belongs to the bytes rather than to one tool-use id.
+ * A retry while the question is pending adopts it instead of asking twice; a
+ * retry after a grant lands proceeds on it, once, inside the TTL. That is why
+ * the wait no longer ends in an immediate withdrawal: a late tap authorizes
+ * something. It ends in one once the RETRY GRACE has run out (APRV-287): past
+ * that window nothing is coming back to adopt the question, and a request left
+ * standing is one more dead message a restarted listener re-delivers.
+ *
+ * **An allow follows its record, and says which window it sits in (APRV-200).**
+ * The harness executes and never sees this process's return value, so what
+ * authorizes the tool call is the record and not the verdict. Every allow that
+ * rests on a grant therefore spends it, RE-READS the verified log to establish
+ * that the `execution.started` is in the chain, and only then prints — a
+ * `hook-grant-unverified` deny where it cannot. The record itself carries
+ * `grant_origin`: `direct` where the tool call that spent the grant is the tool
+ * call that asked for it, `carried` where a later one spent it under the
+ * carryover above. Only `direct` states an ordering this runtime observed;
+ * `carried` is the window in which a grant can be a ratification of a write the
+ * harness already applied, and naming it is what makes that visible to an
+ * 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";
+/**
+ * How much of the command line goes in the (claimed) summary field.
+ *
+ * A HEADLINE, and only that (APRV-124). What the approver is bound to is the
+ * payload, which carries the whole command (or the whole change) and is never
+ * shortened; this is the one-line label above it. Exported because the tests
+ * pin the distinction.
+ */
+export declare const SUMMARY_LIMIT = 160;
+/**
+ * The closed set of hook denial codes, frozen in the sense
+ * `GATE_REFUSAL_CODES` is: the reason string a human reads and an agent
+ * branches on starts with one of these.
+ *
+ * `hook-gate-refused` is a family: the emitted code is
+ * `hook-gate-refused:<gate refusal code>`, so the gate's own frozen vocabulary
+ * reaches the caller unflattened.
+ */
+export declare const HOOK_DENY_CODES: readonly [
+/** No rule covers some segment of the command line. */
+"hook-unclassified", 
+/**
+ * Some class of the command resolves to `human-only` (APRV-185, amended
+ * SPEC.md §5.2): the policy reserves it to human hands, so the command is
+ * denied outright and no gate lifecycle is opened for it.
+ *
+ * This union's spelling of the gate's `class-human-only`, which the detail
+ * names in full. It wears the `hook-` prefix every other member wears rather
+ * than borrowing the gate's bare code, because a caller branching on this
+ * vocabulary branches on one shape; `hook-gate-refused:<c>` is the form
+ * reserved for a code the gate itself produced, and the gate is not asked
+ * here.
+ *
+ * Distinct from `hook-unclassified`, and the repairs are opposites. That one
+ * says the policy has nothing to say about this command, so the fix is to
+ * declare a class for it. This one says the policy has spoken as clearly as
+ * it can, and the fix is for a person to run the command themselves. Distinct
+ * from `hook-rejected` for the reason the gate's code is distinct from a
+ * 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. */
+"hook-unparseable", 
+/** A human rejected the request. */
+"hook-rejected", 
+/** A previously granted request was withdrawn. */
+"hook-revoked", 
+/** The request's TTL lapsed before a decision. */
+"hook-expired", 
+/**
+ * The request was withdrawn before a decision landed (APRV-106). Since
+ * APRV-117 the timeout no longer produces this: what does is a session that
+ * ended mid-wait (signal or failure) and an operator's `approval withdraw`.
+ * Terminal, and not a refusal by anyone.
+ */
+"hook-withdrawn", 
+/**
+ * The wait elapsed with the request still undecided. The request stays open
+ * for the RETRY GRACE (APRV-117, bounded by APRV-287): a decision inside that
+ * window authorizes a retry of the identical command in the identical
+ * 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.
+ */
+"hook-timeout", 
+/** The gate refused intake; the gate's own code follows a colon. */
+"hook-gate-refused", 
+/**
+ * The grant was spent and the VERIFIED log does not show it (APRV-200).
+ *
+ * Distinct from `hook-gate-refused:append-failed`, which says the write was
+ * refused and nothing landed. This one says the write reported success and the
+ * chain cannot be seen to carry it, which is a different fact with a different
+ * repair: nothing here is retried, the log is checked (`approval log verify`).
+ *
+ * On this surface the record IS the authorization — the harness executes and
+ * never sees the gate's return value — so a verdict is not printed until the
+ * verified chain carries the execution the harness is about to perform. The
+ * grant is spent by the time this fires, which is the fail-closed direction:
+ * one more prompt on the retry, and nothing authorized meanwhile.
+ */
+"hook-grant-unverified", 
+/**
+ * `APPROVAL_HOOK_REQUIRE_SANDBOX=1` is set and this command runs code the
+ * runtime did not author, unwrapped (APRV-193).
+ *
+ * The one deny in this union that names a spelling that would work rather
+ * than a decision or a fault: re-run it as `approval sandbox -- <cmd>` and it
+ * proceeds, classified exactly as it is now, with no way out to the network.
+ *
+ * It exists because the hook DECIDES and the harness EXECUTES. A verdict
+ * cannot rewrite a command into a wrapper, so the only way for this runtime
+ * to insist on the room is to refuse the spelling that does not ask for it.
+ * Off by default, and turning it on can only ever refuse more — which is why
+ * an environment variable is an acceptable home for it, and why nothing in
+ * the other direction is readable from one.
+ */
+"hook-sandbox-required", 
+/** The policy could not be loaded, so no class can be resolved. */
+"hook-policy-unavailable", 
+/**
+ * No log exists where the hook was pointed. The hook is a WRITER to an
+ * existing log, never an initializer: creating one where it happens to stand
+ * (an agent worktree, say) forks a chain off the real log's tail, and git
+ * 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;
+    /** One line per downgraded segment; empty when nothing was refined. */
+    notes: string[];
+}
+/**
+ * Downgrade local rewrites of unpublished history to `vcs.commit.branch`.
+ *
+ * IMPURE by design and by contract: it runs git in `cwd`. Both callers pass the
+ * same directory the hook itself resolves from, so what `hook classify` prints
+ * is what `hook claude-code` decides.
+ */
+export declare function refineRewrite(result: CommandClassification, cwd: string): RefinedClassification;
+/**
+ * Is a candidate deep enough, once resolved, to stand as a scratch root?
+ *
+ * The depth floor is the anti-poisoning guard (SPEC.md §11.1: self-reported
+ * fields never reduce scrutiny). A `TMPDIR` naming `/` resolves and exists, and
+ * a root of `/` would turn every absolute delete into a scratch delete, so a
+ * resolved root is refused below {@link MIN_ROOT_SEGMENTS}.
+ *
+ * The well-known system temp roots are the one exception, and they are one on
+ * every platform: on Linux `os.tmpdir()` is `/tmp`, a single segment, and
+ * refusing it would mean `files.delete.scratch` could never fire there, while
+ * on macOS the same directory resolves through the `/tmp` symlink to
+ * `/private/tmp` and clears the floor by accident of layout. The exemption is
+ * keyed on the RESOLVED value being one of the three compiled-in names, so
+ * nothing a caller reports widens it: a poisoned `TMPDIR` still has to resolve
+ * to `/tmp`, `/private/tmp` or `/var/tmp` to get in, and those are roots
+ * already. `/` is not among them, and every other one-segment directory
+ * (`/etc`, `/home`, `/usr`) stays refused.
+ */
+export declare function scratchRootDepthAccepted(resolved: string): boolean;
+/**
+ * The scratch roots this process may vouch for, resolved and guarded.
+ *
+ * `cwd` is the directory the hook itself resolved from; a candidate containing
+ * it is discarded, because a root that swallowed the checkout would make every
+ * delete in the repository a scratch delete.
+ */
+export declare function resolveScratchRoots(cwd: string, env?: NodeJS.ProcessEnv): string[];
+/**
+ * Tighten `files.delete.scratch` back to `files.delete.out_of_scope` wherever
+ * the disk disagrees with the text.
+ *
+ * IMPURE by design and by contract, exactly as {@link refineRewrite} is: it
+ * stats paths. It only ever moves a segment toward the stricter class, so a
+ * caller that skipped it would never be MORE permissive than one that runs it,
+ * which is what lets `hook classify` and `hook claude-code` share it without
+ * either becoming the authority.
+ */
+export declare function refineScratchDelete(result: CommandClassification, roots: readonly string[]): RefinedClassification;
+/**
+ * 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 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, readRoots?: readonly string[]): RefinedClassification;
+/**
+ * What the classifier made of a command (APRV-91 #9).
+ *
+ * Human output is an aligned three-column table under a `key` header row; the
+ * command text and the rule name are copyable and stay undressed. `--json`
+ * emits the classification object unchanged, and asks for the style FIRST so
+ * 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).
+ *
+ * A post-execution hook cannot deny anything — the tool has already run — so
+ * none of these is a verdict, and every one of them prints an EMPTY STDOUT: a
+ * decision object on that stream would be a second answer about a command the
+ * harness already ran. The line goes to stderr instead.
+ *
+ * ## The exit code decides whether anybody reads that line (APRV-303)
+ *
+ * Claude Code's hooks reference states it plainly: stderr from a hook that
+ * exits 0 "goes to the debug log only, never the transcript, and Claude never
+ * sees it", and a post-execution hook that exits 2 has its stderr shown, since
+ * there is nothing left to block. So a refusal reported at exit 0 is a refusal
+ * nobody receives, which is how 22052 unreported starts accumulated on this
+ * project's own log without a single visible complaint.
+ *
+ * Therefore: {@link POST_TOOL_REPORTED} exits 0, because a counterpart that
+ * landed is not news; every other code exits {@link POST_TOOL_SURFACE_EXIT},
+ * because every other code means the outcome of a tool call was not recorded
+ * and somebody has to know. Neither exit is a verdict, and neither blocks
+ * anything.
+ */
+export declare const POST_TOOL_CODES: readonly [
+/** One or more counterparts were appended. */
+"post-tool-reported", 
+/** The event names no tool-use id, so no task id can be reconstructed. */
+"post-tool-unidentified", 
+/** The tool is not one this hook gates, so no start exists to close. */
+"post-tool-not-gated", 
+/**
+ * The outcome could not be read from the event by the pinned set of readings,
+ * so NOTHING was appended. Recording a failure nobody observed trips an
+ * escalation on noise, and recording a completion nobody observed clears one
+ * on nothing.
+ */
+"post-tool-unreadable-outcome", 
+/** No log where the hook was pointed; the hook is a writer, never an initializer. */
+"post-tool-log-unreachable", 
+/** The gate refused the append; its own frozen code follows a colon. */
+"post-tool-gate-refused", 
+/** Malformed input, or a filesystem fact that stopped the report. */
+"post-tool-io"];
+export type PostToolCode = (typeof POST_TOOL_CODES)[number];
+/** The environment variable that turns the sandbox requirement on (APRV-193). */
+export declare const REQUIRE_SANDBOX_ENV = "APPROVAL_HOOK_REQUIRE_SANDBOX";
+/**
+ * Must this command have been written `approval sandbox -- …`? (APRV-193.)
+ *
+ * Returns the deny detail, or `null` to proceed. Four conditions, and every one
+ * of them is a narrowing, so the answer is `null` for everything the operator
+ * did not deliberately ask about:
+ *
+ * 1. the operator set `APPROVAL_HOOK_REQUIRE_SANDBOX=1`;
+ * 2. some segment runs code this runtime did not author
+ *    (`CODE_EXECUTING_RULES`: `npm test`, `node x.mjs`, `tsc`, `make`…);
+ * 3. that segment is not already inside the runtime's own wrapper. A
+ *    hand-written `sandbox-exec -f mine.sb` does NOT satisfy it, because a
+ *    profile a caller wrote can allow everything, and a requirement met by
+ *    writing your own permission is not a requirement;
+ * 4. no class of the command is manual. A manual command is going to a human,
+ *    and a human's grant over these exact bytes is the authority to reach the
+ *    world — the same line `approval run` draws at the token.
+ *
+ * The environment variable is read in the strict direction only: setting it can
+ * refuse commands that would otherwise run, and nothing an agent can set makes
+ * this function return `null` where it would otherwise deny (SPEC.md §11.1
+ * 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 {};