approval-md 0.0.1 → 0.1.0

package/dist/src/cli/hook.js

@@ -0,0 +1,2743 @@
+/**
+ * `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 { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve as resolvePathSegments, sep, } from "node:path";
+import { attestationRefusal, checkAttestation } from "../core/attest.js";
+import { childEnvironment } from "../core/child-env.js";
+import { classifyCommand, commandSegmentWords, CODE_EXECUTING_RULES, GATE_SELF_CLASS, protectedPathClass, } from "../core/command-class.js";
+import { consumeHarnessGrant, findHarnessCarry, finishHarnessExecution, register, request, startHarnessExecution, withdraw, } from "../core/gate.js";
+import { openGateWindow, recordGateBypass, } from "../core/gate-window.js";
+import { harnessProvenance, } from "../core/harness-version.js";
+import { abandonedAfterMs, HOOK_DEFAULT_WAIT, HOOK_RETRY_GRACE_MS, } from "../core/harness-wait.js";
+import { harnessLoopFloor, isLoopEscalated, isSideEffectingClass, loopClearance, UNKNOWN_SESSION, } from "../core/loop.js";
+import { drawSocketPathFor, drawSocketUsable } from "../core/live-draw.js";
+import { payloadHash } from "../core/payload.js";
+import { loadPolicy, parseDuration } from "../core/policy-load.js";
+import { humanOnlyRefusal, resolve as resolvePolicy } from "../core/policy-match.js";
+import { payloadOf, readVerifiedRecords, requestState, useVerifiedSnapshots, } from "../core/state.js";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import { primaryRoot as resolvePrimaryRoot } from "./git-scope.js";
+import { HOOK_HELP } from "./help.js";
+import { DEFAULT_LOG_PATH } from "./paths.js";
+import { refusal as renderRefusal, style, table } from "./style.js";
+import { usageErrorText } from "./usage.js";
+/** Identity accepted for the proposing side: a person or an agent. */
+const PRINCIPAL_ACTOR = /^(human|agent):.+/u;
+/**
+ * Default wait, chosen to sit inside Claude Code's own 60s hook default.
+ *
+ * Spelled in `core/harness-wait.ts` since APRV-287, where the Telegram
+ * listener reads the same duration to decide which pending requests nobody is
+ * waiting on any more.
+ */
+const DEFAULT_TIMEOUT = HOOK_DEFAULT_WAIT;
+/** Poll interval for the decision wait. */
+const DEFAULT_INTERVAL_MS = 1_000;
+/**
+ * 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 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 const HOOK_DENY_CODES = [
+    /** 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 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",
+    /** Malformed hook input, or a log/filesystem fact that stopped the check. */
+    "hook-io",
+];
+const COMMON_FLAGS = {
+    "--help": "boolean",
+    "-h": "boolean",
+};
+const POLICY_FLAGS = {
+    "--policy": "string",
+    "--dir": "string",
+};
+function absolute(value, cwd) {
+    return isAbsolute(value) ? value : resolvePathSegments(cwd, value);
+}
+function usageError(streams, message) {
+    streams.err(usageErrorText(message, HOOK_HELP));
+    return EXIT_USAGE;
+}
+/**
+ * The primary checkout containing `cwd`, or `null` when git cannot say.
+ *
+ * `git rev-parse --git-common-dir` names the SHARED git directory: in a linked
+ * worktree it is the primary checkout's `.git`, in a plain checkout it is this
+ * checkout's own (printed as bare `.git` at the top level, absolute from a
+ * subdirectory). Either way the primary root is its parent, so a plain checkout
+ * resolves to itself.
+ *
+ * Run exactly as `amend.ts` runs git: `spawnSync`, no shell, and every failure
+ * is a value. When git is absent, or `cwd` is not a repository at all, this
+ * returns `null` and the caller falls back to `cwd` — today's behaviour, which
+ * is what a non-git deployment of the hook has always relied on.
+ *
+ * APRV-125 gave the resolution two more callers (`log sync` and `log advance`,
+ * which refuse outside the primary rather than falling back), so the
+ * implementation moved to `cli/git-scope.ts`. This alias keeps the hook reading
+ * the same answer they read.
+ */
+const primaryRoot = resolvePrimaryRoot;
+/**
+ * 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.
+ */
+function hookScope(flags, cwd) {
+    const policyFlag = stringFlag(flags, "--policy");
+    const logFlag = stringFlag(flags, "--log");
+    const dirFlag = stringFlag(flags, "--dir");
+    const root = dirFlag !== null ? absolute(dirFlag, cwd) : (primaryRoot(cwd) ?? cwd);
+    const options = policyFlag === null
+        ? { policy: { dir: root } }
+        : { policy: { file: absolute(policyFlag, cwd) } };
+    const logPath = logFlag === null ? join(root, DEFAULT_LOG_PATH) : absolute(logFlag, cwd);
+    return { logPath, root, options };
+}
+const CLAUDE_ADAPTER = {
+    kind: "claude-code",
+    originApp: "claude-code-hook",
+    defaultActor: "agent:claude-code",
+    shellTool: "Bash",
+    fileTools: ["Edit", "Write", "MultiEdit", "NotebookEdit"],
+};
+const CURSOR_ADAPTER = {
+    kind: "cursor",
+    originApp: "cursor-hook",
+    defaultActor: "agent:cursor",
+    shellTool: "Shell",
+    fileTools: ["Write", "Delete"],
+};
+/**
+ * The decision object the harness reads from stdout.
+ *
+ * Claude Code wants the nested PreToolUse envelope. Cursor native hooks want
+ * `{permission, user_message, agent_message}`. One construction site per
+ * harness, still never `ask`.
+ */
+function decision(permission, reason, harness) {
+    if (harness === "cursor") {
+        return `${JSON.stringify({
+            permission,
+            user_message: reason,
+            agent_message: reason,
+        })}\n`;
+    }
+    return `${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: permission,
+            permissionDecisionReason: reason,
+        },
+    })}\n`;
+}
+function allow(streams, reason, harness) {
+    streams.out(decision("allow", reason, harness));
+    return EXIT_OK;
+}
+function deny(streams, code, detail, harness) {
+    streams.out(decision("deny", `${code}: ${detail}`, harness));
+    return EXIT_OK;
+}
+function readString(source, key) {
+    const value = source[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * Parse the PreToolUse JSON.
+ *
+ * Deliberately tolerant about fields the decision does not depend on and strict
+ * about the two it does (`tool_name`, and `tool_input.command` for Bash). The
+ * `description` field is NEVER read: it is authored by the agent being gated,
+ * and a gate that read the subject's own account of its intent would be letting
+ * a self-reported field reduce scrutiny (SPEC.md §11.1).
+ */
+function parseHookInput(raw) {
+    if (raw.trim().length === 0)
+        return { ok: false, detail: "hook stdin was empty" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            detail: `hook stdin is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, detail: "hook stdin is not a JSON object" };
+    }
+    const fields = parsed;
+    const toolName = readString(fields, "tool_name");
+    if (toolName === null)
+        return { ok: false, detail: "hook input has no tool_name" };
+    const toolInputValue = fields["tool_input"];
+    const toolInput = typeof toolInputValue === "object" && toolInputValue !== null && !Array.isArray(toolInputValue)
+        ? toolInputValue
+        : {};
+    const responseValue = fields["tool_response"];
+    return {
+        ok: true,
+        input: {
+            // The ONE shared bucket for an unreadable session (`core/loop.ts`'s
+            // `UNKNOWN_SESSION`): absence accrues faster than a readable id and never
+            // slower, which is the fail-closed direction.
+            sessionId: readString(fields, "session_id") ?? UNKNOWN_SESSION,
+            cwd: readString(fields, "cwd") ?? "",
+            toolName,
+            toolInput,
+            toolUseId: readString(fields, "tool_use_id"),
+            hookEventName: readString(fields, "hook_event_name"),
+            harnessVersion: readString(fields, "version"),
+            interrupted: fields["is_interrupt"] === true,
+            toolResponse: typeof responseValue === "object" && responseValue !== null && !Array.isArray(responseValue)
+                ? responseValue
+                : null,
+        },
+    };
+}
+// ===========================================================================
+// History-rewrite refinement (APRV-108)
+// ===========================================================================
+/*
+ * Rewriting history nobody else holds is a commit.
+ *
+ * `vcs.history.rewrite` exists to guard SHARED history: a force push, a rebase
+ * of a branch other people have pulled, an amend of a commit that is already on
+ * the remote. An agent amending its own unpublished worktree branch destroys
+ * nothing anyone can observe, and pricing that at a human's attention spends the
+ * audit budget SPEC.md §11 asks to protect on a non-event.
+ *
+ * The classifier cannot answer this, and deliberately does not try: it is pure,
+ * and "is this branch published" is a fact about a checkout, not about a string.
+ * So the refinement lives HERE, in the impure layer that already runs git
+ * (`primaryRoot`, APRV-101), and is applied to the classifier's output rather
+ * than folded into it. `classifyCommand` keeps returning `vcs.history.rewrite`
+ * for these verbs, its fixture table keeps meaning what it says, and everything
+ * environment-dependent is in one named step a reader can audit.
+ *
+ * What downgrades, and only this:
+ *
+ *  - the branch has NO upstream at all — nothing was ever published from it, so
+ *    no rewrite of it can reach anyone else; or
+ *  - the command is `git commit --amend` and HEAD is not reachable from the
+ *    upstream — the one commit an amend rewrites has not been pushed.
+ *
+ * What never downgrades: anything push-side (`git push --force` and friends),
+ * a detached HEAD, the repository's default branch, a rebase or reset whose
+ * target the text does not name (a `git reset --hard HEAD~5` on a branch with an
+ * upstream may well be rewriting published commits, and the text cannot say), and
+ * every case where git declines to answer. Fail closed on each: a wrong
+ * downgrade removes a human from a decision that needed one, and a wrong
+ * `rewrite` costs one approval prompt.
+ */
+/**
+ * Classifier rules whose rewrite is LOCAL, and so can be refined.
+ *
+ * `git-push-force` is deliberately absent: a push is a rewrite of the remote by
+ * construction, whatever this checkout's branch state is.
+ */
+const LOCAL_REWRITE_RULES = [
+    /** `git commit --amend`. */
+    "git-commit-amend",
+    /** `git reset --hard`. */
+    "git-reset-hard",
+    /** `git rebase` / `filter-branch` / `filter-repo` (the table row's own id). */
+    "git-rewrite",
+];
+/** The one rule whose rewritten commit is exactly HEAD. */
+const AMEND_RULE = "git-commit-amend";
+/** The rule name a refined segment reports, in `hook classify` and in tests. */
+const REWRITE_UNPUBLISHED_RULE = "rewrite-unpublished";
+const REWRITE_CLASS = "vcs.history.rewrite";
+const UNPUBLISHED_CLASS = "vcs.commit.branch";
+/**
+ * The environment every git child of this verb receives (APRV-205).
+ *
+ * The hook spawns no granted command — it answers allow or deny and the harness
+ * runs the command itself — so nothing here is the task's load-bearing case.
+ * These git children are still children of a process holding the session's
+ * credentials, and `git rev-parse` has no use for a Telegram token. Built
+ * through the one helper so there is one list.
+ */
+function gitEnvironment() {
+    return childEnvironment().env;
+}
+/** Trimmed stdout of a successful git command, or `null` for any failure. */
+function gitOutput(cwd, args) {
+    const result = spawnSync("git", [...args], { cwd, encoding: "utf8", env: gitEnvironment() });
+    if (result.error !== undefined || result.status !== 0)
+        return null;
+    return result.stdout.trim();
+}
+/**
+ * `git merge-base --is-ancestor` as three values, not two.
+ *
+ * Exit 0 is yes and exit 1 is no; every other exit (a missing ref, a broken
+ * repository, no git at all) is `null`, which the caller reads as "stay a
+ * rewrite" rather than as "no".
+ */
+function isAncestor(cwd, ancestor, descendant) {
+    const result = spawnSync("git", ["merge-base", "--is-ancestor", ancestor, descendant], {
+        cwd,
+        encoding: "utf8",
+        env: gitEnvironment(),
+    });
+    if (result.error !== undefined)
+        return null;
+    if (result.status === 0)
+        return true;
+    if (result.status === 1)
+        return false;
+    return null;
+}
+/**
+ * Is this the branch a rewrite must never be quiet about?
+ *
+ * `main` and `master` always count, whatever the remote says, so a local-only
+ * repository (and a branch someone named `main` in a scratch checkout) is
+ * covered. `refs/remotes/origin/HEAD` adds the remote's own answer when it is
+ * set, which is how a repository whose trunk is `develop` or `trunk` is read.
+ */
+function isDefaultBranch(cwd, branch) {
+    if (branch === "main" || branch === "master")
+        return true;
+    const head = gitOutput(cwd, ["symbolic-ref", "refs/remotes/origin/HEAD"]);
+    if (head === null || head.length === 0)
+        return false;
+    return head.replace(/^refs\/remotes\/origin\//u, "") === branch;
+}
+/**
+ * Ask git how far the checkout at `cwd` has been published.
+ *
+ * Every step that cannot be answered returns `shared`, which refines nothing.
+ * `for-each-ref` rather than `@{u}` on purpose: `rev-parse @{u}` exits non-zero
+ * both when there is no upstream and when the repository cannot be read, and
+ * those two must not collapse — one downgrades, the other must not.
+ */
+function rewriteReach(cwd) {
+    const branch = gitOutput(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    // No git, not a repository, or a detached HEAD (which prints `HEAD`): a
+    // detached rewrite has no branch whose publication could be checked.
+    if (branch === null || branch.length === 0 || branch === "HEAD")
+        return { kind: "shared" };
+    if (isDefaultBranch(cwd, branch))
+        return { kind: "shared" };
+    // Exits 0 and prints an empty line when the branch tracks nothing, so an
+    // empty result is a real answer and a failure is not.
+    const upstream = gitOutput(cwd, [
+        "for-each-ref",
+        "--format=%(upstream:short)",
+        `refs/heads/${branch}`,
+    ]);
+    if (upstream === null)
+        return { kind: "shared" };
+    if (upstream.length === 0)
+        return { kind: "no-upstream", branch };
+    // An upstream is configured. HEAD reachable from it (or unanswerable, e.g. a
+    // tracking ref that was never fetched) stays a rewrite.
+    return isAncestor(cwd, "HEAD", upstream) === false
+        ? { kind: "head-unpushed", branch, upstream }
+        : { kind: "shared" };
+}
+/**
+ * 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 function refineRewrite(result, cwd) {
+    if (!result.ok)
+        return { result, notes: [] };
+    const refinable = result.segments.some((segment) => segment.class === REWRITE_CLASS && LOCAL_REWRITE_RULES.includes(segment.rule));
+    if (!refinable)
+        return { result, notes: [] };
+    const reach = rewriteReach(cwd);
+    if (reach.kind === "shared")
+        return { result, notes: [] };
+    const notes = [];
+    const segments = result.segments.map((segment) => {
+        if (segment.class !== REWRITE_CLASS || !LOCAL_REWRITE_RULES.includes(segment.rule)) {
+            return segment;
+        }
+        // With an upstream, only an amend is narrow enough to be sure: it rewrites
+        // HEAD and nothing else. A rebase or reset names a base the text cannot
+        // resolve, so it may reach commits that ARE on the upstream.
+        if (reach.kind === "head-unpushed" && segment.rule !== AMEND_RULE)
+            return segment;
+        notes.push(reach.kind === "no-upstream"
+            ? `${REWRITE_UNPUBLISHED_RULE}: branch ${reach.branch} has no upstream, so \`${segment.text}\` rewrites only unpublished history`
+            : `${REWRITE_UNPUBLISHED_RULE}: HEAD is not yet on ${reach.upstream}, so \`${segment.text}\` amends only unpublished history`);
+        return { ...segment, class: UNPUBLISHED_CLASS, rule: REWRITE_UNPUBLISHED_RULE };
+    });
+    if (notes.length === 0)
+        return { result, notes };
+    const classes = [];
+    for (const segment of segments) {
+        if (!classes.includes(segment.class))
+            classes.push(segment.class);
+    }
+    return { result: { ok: true, segments, classes }, notes };
+}
+// ===========================================================================
+// Scratch-delete refinement (APRV-267)
+// ===========================================================================
+/*
+ * Where the agent's own scratch space is, and whether a delete really stays
+ * inside it.
+ *
+ * The classifier cannot answer either question. It is pure over command text,
+ * and "is this path under the scratchpad this process was allotted" is a fact
+ * about a machine. So the work splits the way APRV-108's rewrite refinement
+ * split: `command-class.ts` compares path segments against roots it is HANDED
+ * (`ClassifierContext.scratchRoots`), and everything that needs a disk or an
+ * environment lives here, in the impure layer that already runs git.
+ *
+ * ## What the roots are read from
+ *
+ * No harness exports the session scratchpad as an environment variable today.
+ * Claude Code names it in the system prompt and nowhere else, and this process
+ * inherits no `CLAUDE_SCRATCHPAD*` and no `TMPDIR` from it. So the roots are
+ * built from what a process CAN observe:
+ *
+ *  - `CLAUDE_SCRATCHPAD_DIR` and `CLAUDE_CODE_SCRATCHPAD_DIR`, read if a
+ *    harness ever starts exporting them, so that the day it does the rule is
+ *    already narrow enough to name one session's own directory;
+ *  - `os.tmpdir()`, which is where every observed scratchpad actually lives
+ *    (`/private/tmp/claude-501/<project>/<session>/scratchpad` on this Mac);
+ *  - the fixed platform temp roots `/tmp` and `/var/tmp`, plus `/private/tmp`
+ *    on macOS, where `/tmp` is a symlink to it.
+ *
+ * ## Why nothing an agent controls widens the class
+ *
+ * SPEC.md §11.1: self-reported fields never reduce scrutiny. `os.tmpdir()`
+ * reads `TMPDIR`, so a poisoned value could in principle nominate `/` and turn
+ * every absolute delete into a scratch delete. Three guards close that, and
+ * none of them trusts the value: a root must resolve to a real directory, must
+ * clear the depth floor, and must not contain the directory the hook was
+ * invoked in. A checkout is never inside its own scratch root.
+ *
+ * The depth floor is two path segments, so `/` and one-segment directories like
+ * `/etc` are out, with the three compiled-in temp roots (`/tmp`, `/private/tmp`,
+ * `/var/tmp`) exempt from it because on Linux `os.tmpdir()` IS `/tmp`, a single
+ * segment. See {@link scratchRootDepthAccepted} for why that exemption cannot
+ * be reached by a poisoned value.
+ *
+ * ## Why the second pass exists at all
+ *
+ * A path can be textually under a root and physically somewhere else (a symlink
+ * in the middle of it), and a git checkout can live inside the temp root
+ * (`/tmp/probe-clone`), where a delete destroys work rather than tidying up.
+ * Neither is visible in the argv. So this pass re-reads each target, resolves
+ * the nearest ancestor that exists, and TIGHTENS back to
+ * `files.delete.out_of_scope` on any doubt: a target it cannot resolve, a
+ * resolution that leaves the root, a `.git` at or above the target.
+ */
+/** The class the classifier hands over, and the one this pass falls back to. */
+const OUT_OF_SCOPE_CLASS = "files.delete.out_of_scope";
+/** The classifier rule whose segments this pass re-reads. */
+const SCRATCH_RULE = "rm-scratch";
+/** The rule a tightened segment reports. */
+const SCRATCH_REJECTED_RULE = "rm-scratch-rejected";
+/**
+ * Environment variables a HARNESS may use to name the session scratchpad.
+ *
+ * None is set by any harness this runtime has seen; they are read so the rule
+ * narrows the day one starts exporting it, rather than staying pinned to the
+ * whole temp root forever. A value that fails any of the guards (absolute, a
+ * real directory, deep enough, clear of the cwd) is ignored like any other
+ * candidate.
+ */
+const SCRATCHPAD_ENV_NAMES = [
+    "CLAUDE_SCRATCHPAD_DIR",
+    "CLAUDE_CODE_SCRATCHPAD_DIR",
+];
+/**
+ * Fixed temp roots, beyond whatever `os.tmpdir()` reports.
+ *
+ * These are the well-known system temp directories, and the depth rule below
+ * exempts them: they are compiled-in constants, not anything a caller reports.
+ */
+const FIXED_TEMP_ROOTS = ["/tmp", "/private/tmp", "/var/tmp"];
+/** Segments a root must have when it is not one of {@link FIXED_TEMP_ROOTS}. */
+const MIN_ROOT_SEGMENTS = 2;
+/** Non-empty path segments in `path`. */
+function segmentDepth(path) {
+    return path.split(sep).filter((segment) => segment.length > 0).length;
+}
+/**
+ * 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 function scratchRootDepthAccepted(resolved) {
+    if (FIXED_TEMP_ROOTS.includes(resolved))
+        return true;
+    return segmentDepth(resolved) >= MIN_ROOT_SEGMENTS;
+}
+/** `realpathSync`, or `null` for anything that does not resolve. */
+function resolvedPath(candidate) {
+    try {
+        return realpathSync(candidate);
+    }
+    catch {
+        return null;
+    }
+}
+/** Is `candidate` a strict descendant of `root`, by path segment? */
+function isBelow(candidate, root) {
+    const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
+    return candidate.startsWith(prefix) && candidate.length > prefix.length;
+}
+/**
+ * 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 function resolveScratchRoots(cwd, env = process.env) {
+    const resolvedCwd = resolvedPath(cwd) ?? cwd;
+    const candidates = [];
+    for (const name of SCRATCHPAD_ENV_NAMES) {
+        const value = env[name];
+        if (typeof value === "string" && value.length > 0)
+            candidates.push(value);
+    }
+    candidates.push(tmpdir(), ...FIXED_TEMP_ROOTS);
+    const roots = [];
+    for (const candidate of candidates) {
+        if (!isAbsolute(candidate))
+            continue;
+        const resolved = resolvedPath(candidate);
+        if (resolved === null)
+            continue;
+        if (!scratchRootDepthAccepted(resolved))
+            continue;
+        if (resolved === resolvedCwd || isBelow(resolvedCwd, resolved))
+            continue;
+        if (!roots.includes(resolved))
+            roots.push(resolved);
+    }
+    return roots;
+}
+/**
+ * Is there a `.git` at `target` or above it, stopping at `root`?
+ *
+ * `root` itself is checked too: a checkout whose top IS a scratch root would
+ * otherwise hide from the walk. Any filesystem error answers `true`, because an
+ * unreadable directory is not one this pass may vouch for.
+ */
+function insideCheckout(target, root) {
+    let at = target;
+    for (let depth = 0; depth < 64; depth += 1) {
+        try {
+            if (existsSync(join(at, ".git")))
+                return true;
+        }
+        catch {
+            return true;
+        }
+        if (at === root)
+            return false;
+        const up = dirname(at);
+        if (up === at)
+            return true;
+        at = up;
+    }
+    return true;
+}
+/**
+ * Does this one target survive the physical checks?
+ *
+ * The target itself may or may not exist, so the nearest EXISTING ancestor is
+ * resolved and the unresolved tail re-appended. A symlink anywhere in that
+ * ancestor chain therefore cannot smuggle the path out of the root, which is
+ * the escape the pure half cannot see.
+ */
+function targetStaysInScratch(target, roots) {
+    let existing = target;
+    const tail = [];
+    for (let depth = 0; depth < 64; depth += 1) {
+        if (existsSync(existing))
+            break;
+        const up = dirname(existing);
+        if (up === existing)
+            return false;
+        tail.unshift(basename(existing));
+        existing = up;
+    }
+    const resolved = resolvedPath(existing);
+    if (resolved === null)
+        return false;
+    const full = tail.length === 0 ? resolved : join(resolved, ...tail);
+    const root = roots.find((candidate) => isBelow(full, candidate));
+    if (root === undefined)
+        return false;
+    return !insideCheckout(full, root);
+}
+/**
+ * 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 function refineScratchDelete(result, roots) {
+    if (!result.ok)
+        return { result, notes: [] };
+    if (!result.segments.some((segment) => segment.rule === SCRATCH_RULE)) {
+        return { result, notes: [] };
+    }
+    const notes = [];
+    const segments = result.segments.map((segment) => {
+        if (segment.rule !== SCRATCH_RULE)
+            return segment;
+        const reject = (detail) => {
+            notes.push(`${SCRATCH_REJECTED_RULE}: ${detail}`);
+            return { ...segment, class: OUT_OF_SCOPE_CLASS, rule: SCRATCH_REJECTED_RULE };
+        };
+        const words = commandSegmentWords(segment.text);
+        const parsed = words === null ? undefined : words[0];
+        // The classifier read this segment a moment ago, so a parse that disagrees
+        // here is two reads of the same bytes disagreeing. Fail closed.
+        if (parsed === undefined) {
+            return reject(`\`${segment.text}\` could not be re-read, so it stays ${OUT_OF_SCOPE_CLASS}`);
+        }
+        const targets = parsed.args.filter((arg) => !arg.startsWith("-") || arg === "-");
+        if (targets.length === 0) {
+            return reject(`\`${segment.text}\` names no target, so it stays ${OUT_OF_SCOPE_CLASS}`);
+        }
+        const escaped = targets.find((target) => !targetStaysInScratch(target, roots));
+        if (escaped === undefined)
+            return segment;
+        return reject(`${escaped} does not resolve to a path inside a scratch root clear of any git checkout, so \`${segment.text}\` stays ${OUT_OF_SCOPE_CLASS}`);
+    });
+    if (notes.length === 0)
+        return { result, notes };
+    const classes = [];
+    for (const segment of segments) {
+        if (!classes.includes(segment.class))
+            classes.push(segment.class);
+    }
+    return { result: { ok: true, segments, classes }, notes };
+}
+/**
+ * The classifier, its scratch context, and both 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.
+ */
+export function classifyForHook(command, protectedPaths, cwd) {
+    const roots = resolveScratchRoots(cwd);
+    const classified = classifyCommand(command, protectedPaths, { scratchRoots: roots });
+    const rewritten = refineRewrite(classified, cwd);
+    const scratched = refineScratchDelete(rewritten.result, roots);
+    return {
+        result: scratched.result,
+        notes: [...rewritten.notes, ...scratched.notes],
+    };
+}
+// ===========================================================================
+// hook classify
+// ===========================================================================
+/**
+ * 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 function renderClassification(result, json, st = style({ json })) {
+    if (json)
+        return `${JSON.stringify(result)}\n`;
+    if (!result.ok) {
+        // APRV-102: the shared refusal shape rather than a second copy of it. The
+        // segment is a copyable value on its own line, which is what `refusal`'s
+        // optional second line is for.
+        return `${renderRefusal(st, result.code, result.detail)}\n  ${st.key("segment:")} ${result.segment}\n`;
+    }
+    const rows = result.segments.map((segment) => [segment.class, segment.rule, segment.text]);
+    return `${table(st, rows, { header: ["class", "rule", "command"] })}\n\n${st.key("classes:")} ${result.classes.join(", ")}\n`;
+}
+/**
+ * `approval hook classify <command…>` — what the classifier makes of a command.
+ *
+ * Everything after `--` is the command verbatim, which is how a command with
+ * its own flags is passed without this parser claiming them.
+ *
+ * It reads the policy for the same reason `hook claude-code` does (APRV-107):
+ * `policy.protected_paths` widens the protected surface, and an explainer
+ * that answered from the built-ins alone would tell an agent a gated file is
+ * ungated. `--dir` / `--policy` scope it exactly as they scope the hook. This
+ * verb decides nothing and writes nothing, so an unreadable policy is not a
+ * refusal here: it classifies against the built-ins and says on stderr that the
+ * answer is the narrow one.
+ */
+function commandClassify(argv, streams, cwd) {
+    const separator = argv.indexOf("--");
+    const head = separator === -1 ? argv : argv.slice(0, separator);
+    const tail = separator === -1 ? [] : argv.slice(separator + 1);
+    const parsed = parseFlags(head, { ...COMMON_FLAGS, ...POLICY_FLAGS, "--json": "boolean" });
+    if (!parsed.ok) {
+        return usageError(streams, `${parsed.message}; flags belonging to the command being classified must follow \`--\``);
+    }
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${HOOK_HELP}\n`);
+        return EXIT_OK;
+    }
+    const command = [...parsed.positionals, ...tail].join(" ").trim();
+    if (command.length === 0) {
+        return usageError(streams, "missing <command> argument for `approval hook classify`");
+    }
+    const { options } = hookScope(parsed.flags, cwd);
+    const load = loadPolicy(options.policy?.file === undefined
+        ? { dir: options.policy?.dir ?? cwd }
+        : { file: options.policy.file });
+    if (!load.ok) {
+        streams.err(`note: no policy read (${load.code}: ${load.message}); classifying against the built-in protected paths only\n`);
+    }
+    const protectedPaths = load.ok ? (load.policy.protected_paths ?? []) : [];
+    // The same impure refinements `hook claude-code` applies (APRV-108,
+    // APRV-267), run against the same directory: an explainer that printed the
+    // pure class where the hook decides a refined one would be explaining a
+    // different program.
+    streams.out(renderClassification(classifyForHook(command, protectedPaths, cwd).result, boolFlag(parsed.flags, "--json")));
+    return EXIT_OK;
+}
+function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function truncate(text, limit) {
+    const collapsed = text.replace(/\s+/gu, " ").trim();
+    return collapsed.length <= limit ? collapsed : `${collapsed.slice(0, limit - 1)}…`;
+}
+// ===========================================================================
+// File tools: the change, and which checkout it lands in (APRV-124)
+// ===========================================================================
+/**
+ * The rule a protected-path file touch reports, on the SAME class.
+ *
+ * Three tiers, and the class is whichever protected class the path selects
+ * (APRV-198: `policy.edit`, `policy.core` or `log.mutate`); the tier never
+ * changes it. A protected touch inside an agent worktree is a branch
+ * PROPOSAL: the file it writes is a copy on a branch, and the merge that makes
+ * it real is separately gated (`vcs.push.main`, `gh pr merge`). The same touch
+ * in the live checkout is the file itself. A protected name that resolves
+ * OUTSIDE the gated checkout altogether (a scratchpad `APPROVAL.md`, a demo
+ * fixture) is neither: the match is on the name, and the name is all it shares
+ * with the live policy (APRV-161). The approver was being told the same thing
+ * about all three, which is the "truthful label" half of this task.
+ *
+ * The distinction is deliberately NOT a class and NOT an autonomy: policy
+ * semantics are untouched here, every tier resolves exactly as the path's own
+ * protected class resolves, and APRV-127 is where sampling may hang off it.
+ * What changes is what the human reads.
+ */
+const PROTECTED_PATH_RULE = "protected-path";
+const PROTECTED_PATH_PROPOSAL_RULE = "protected-path-proposal";
+const PROTECTED_NAME_ELSEWHERE_RULE = "protected-name-elsewhere";
+/** Where agent worktrees live, relative to the primary root. */
+const WORKTREE_DIR = [".claude", "worktrees"];
+/** `realpathSync`, as a value. */
+function realOrNull(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `path` with every existing ancestor resolved through its symlinks.
+ *
+ * A `Write` names a file that need not exist yet, and a comparison of an
+ * unresolved path against a resolved root answers "no" for the wrong reason on
+ * any machine where the checkout sits under a symlink (`/tmp` on macOS, every
+ * home directory behind an automounter). So the deepest existing ancestor is
+ * resolved and the remainder is joined back on.
+ */
+function resolveExisting(path) {
+    let current = path;
+    const tail = [];
+    for (;;) {
+        const real = realOrNull(current);
+        if (real !== null)
+            return tail.length === 0 ? real : join(real, ...tail);
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        tail.unshift(basename(current));
+        current = parent;
+    }
+}
+/**
+ * The tier `target` sits in, resolved once, from the hook's own directory.
+ *
+ * FAIL CLOSED, on every axis: anything not *provably* inside
+ * `<primary>/.claude/worktrees/<name>/…` and not *provably* outside the primary
+ * root is live-tier. A wrong "proposal" tells a human their APPROVAL.md edit is
+ * a branch copy when it is the live file; a wrong "elsewhere" tells them a
+ * scratch file is being edited when the live policy is; a wrong "live" costs
+ * nothing but a sterner sentence.
+ *
+ * Order matters. The proposal test runs first and against the worktrees
+ * directory's own resolved path, so a worktrees directory reached through a
+ * symlink stays a proposal rather than falling out of the root comparison.
+ *
+ * The primary root comes from `primaryRoot`, i.e. from git run in the hook's
+ * OWN process directory (APRV-108's discipline). The harness-supplied `cwd`
+ * field is never consulted: it is authored by the party under oversight, and a
+ * tier that could be chosen by the subject of the gate is not a tier.
+ */
+function tierOf(target, cwd) {
+    const live = (root) => ({
+        rule: PROTECTED_PATH_RULE,
+        worktree: null,
+        root,
+    });
+    const root = primaryRoot(cwd);
+    if (root === null)
+        return live(null);
+    const file = resolveExisting(target);
+    if (file === null)
+        return live(root);
+    const base = resolveExisting(join(root, ...WORKTREE_DIR));
+    if (base !== null && file.startsWith(`${base}${sep}`)) {
+        const rest = file.slice(base.length + 1).split(sep);
+        // `rest[0]` is the worktree; a target that IS the worktrees directory or a
+        // worktree root names no file inside one and stays live-tier.
+        const name = rest[0];
+        if (name !== undefined && name.length > 0 && rest.length >= 2) {
+            return { rule: PROTECTED_PATH_PROPOSAL_RULE, worktree: name, root };
+        }
+    }
+    const realRoot = resolveExisting(root);
+    if (realRoot === null)
+        return live(root);
+    if (file === realRoot || file.startsWith(`${realRoot}${sep}`))
+        return live(realRoot);
+    return { rule: PROTECTED_NAME_ELSEWHERE_RULE, worktree: null, root: realRoot };
+}
+/**
+ * The class an ordinary file edit is (APRV-303).
+ *
+ * The same string `core/command-class.ts` gives a shell redirect into the
+ * workspace, and spelled here because the file tools reach the same class by a
+ * different road. Until APRV-303 the file path produced no class at all for a
+ * non-protected target, which is why the loop floor could not see an Edit.
+ */
+const WORKSPACE_WRITE_CLASS = "files.write.workspace";
+/**
+ * What a non-Bash tool call asks for, or `null` when it names no file at all.
+ *
+ * Only one thing about a file edit is a gate question at v0.1: whether the file
+ * is one only a human may write. Everything else the harness edits is
+ * `files.write.workspace`, which this repository's policy makes autonomous, and
+ * routing every keystroke of ordinary editing through a gate check would spend
+ * latency to reach a foregone conclusion.
+ *
+ * ## The ordinary edit still gets a class (APRV-303)
+ *
+ * It used to get none: an unprotected target returned `null` here, and
+ * `describeToolCall` answered `allow` from a branch that sits ABOVE the loop
+ * floor, above `recordUnattended`, and above everything that appends. So a
+ * session three failed writes deep had its Bash calls routed to a human and its
+ * Edit calls waved through, which is the disagreement APRV-303 was filed on:
+ * eight edits to the same file, under a standing floor, none of them routed and
+ * none of them counted.
+ *
+ * The foregone conclusion is still foregone, and is still answered without
+ * asking anybody: `describeToolCall` marks the call {@link FileGate.protectedPath}
+ * `false`, and `runHarnessHook` allows it outright the moment it establishes
+ * that no floor is standing. What it can no longer do is skip that
+ * establishment. The floor predicate is now one predicate over one class for
+ * every tool kind, which is what amended SPEC.md §10.2 asks for.
+ *
+ * ## The payload is the change (APRV-124)
+ *
+ * It used to be `{command: "Edit <path>", cwd}` — the *touch*. A human reading
+ * that was asked to approve "an edit to CI config", with no way to tell a typo
+ * fix from a disabled test job; the observed complaint (2026-08-20) is exactly
+ * "I don't know what the actual CI edit is". The PreToolUse event carries the
+ * whole change, so the payload does too:
+ *
+ * - `Edit` → `{tool, rule, file, before, after}` (plus `replace_all` when the
+ *   call sets it, because "replace every occurrence" is part of what is being
+ *   approved and two calls differing only in it are two different questions);
+ * - `Write` → `{tool, rule, file, content}`;
+ * - every other file tool → the same head plus its `tool_input` verbatim under
+ *   `input`, which renders as JSON rather than as a diff but hides nothing.
+ *
+ * Those bytes are what `payload_hash` binds, so the grant binds to the edit.
+ * They are also what APRV-117's carryover keys on: an identical retry of the
+ * identical edit hashes identically and adopts or carries the same question, a
+ * changed edit is a new question, and a proposal-tier grant cannot be spent on
+ * the live file because the absolute `file` differs.
+ *
+ * `description` is dropped on the way in: it is the agent's account of its own
+ * intent, and it has no business in the bytes a human is bound to.
+ */
+function fileToolGate(toolName, toolInput, protectedPaths, cwd) {
+    const declared = readString(toolInput, "file_path") ??
+        readString(toolInput, "notebook_path") ??
+        readString(toolInput, "path");
+    if (declared === null)
+        return null;
+    // The SAME split the shell classifier applies (APRV-198): a file tool aimed
+    // at APPROVAL.md or the approval home is `policy.core`, one aimed at
+    // `.approval/log/` is `log.mutate`, and only the prose-and-configuration
+    // surface stays `policy.edit`. Editing through the Edit tool must not be a
+    // cheaper way to touch the gate than editing through a shell redirect.
+    const surface = protectedPathClass(declared, protectedPaths);
+    const file = absolute(declared, cwd);
+    const tier = tierOf(file, cwd);
+    const rule = tier.rule;
+    const head = { tool: toolName, rule, file };
+    const before = toolInput["old_string"];
+    const after = toolInput["new_string"];
+    const content = toolInput["content"] ?? toolInput["contents"];
+    const replaceAll = toolInput["replace_all"];
+    let payload;
+    if (typeof before === "string" && typeof after === "string") {
+        payload =
+            typeof replaceAll === "boolean"
+                ? { ...head, replace_all: replaceAll, before, after }
+                : { ...head, before, after };
+    }
+    else if (typeof content === "string") {
+        payload = { ...head, content };
+    }
+    else {
+        const input = { ...toolInput };
+        delete input["description"];
+        payload = { ...head, input };
+    }
+    return {
+        cls: surface ?? WORKSPACE_WRITE_CLASS,
+        protectedPath: surface !== null,
+        rule,
+        file,
+        worktree: tier.worktree,
+        root: tier.root,
+        payload,
+        // The tier leads the headline rather than trailing it: a summary is
+        // truncated from the right, and the qualifier is the last thing that may
+        // be ellipsized away (a long path is not — the payload carries it whole).
+        summary: summaryFor(tier, toolName, file),
+    };
+}
+/** The headline for a tier: the qualifier first, the touch after it. */
+function summaryFor(tier, toolName, file) {
+    if (tier.worktree !== null) {
+        return `branch proposal (worktree ${tier.worktree}): ${toolName} ${file}`;
+    }
+    if (tier.rule === PROTECTED_NAME_ELSEWHERE_RULE) {
+        return `file named like a policy file, outside this gated checkout: ${toolName} ${file}`;
+    }
+    return `${toolName} ${file}`;
+}
+/**
+ * The tier, in the verdict's note, so an `allow` says what it authorized.
+ *
+ * The elsewhere arm names the root it was decided against, because "outside the
+ * gated checkout" is only readable next to which checkout that is.
+ */
+function fileTierNote(gated) {
+    if (gated.worktree !== null) {
+        return `${gated.rule}: ${gated.file} is inside agent worktree ${gated.worktree}, so this is a branch proposal and the merge to the live checkout is gated separately`;
+    }
+    if (gated.rule === PROTECTED_NAME_ELSEWHERE_RULE) {
+        return `${gated.rule}: ${gated.file} is NAMED like a policy file but sits outside the gated checkout ${gated.root ?? "(unresolved)"}, so it is not this repository's live policy; it is gated because a protected name is protected wherever it sits`;
+    }
+    return `${gated.rule}: ${gated.file} is the LIVE checkout's copy`;
+}
+/**
+ * The provenance pair to stamp on a record this invocation is about to write,
+ * or `null` when this process cannot establish one (APRV-227).
+ *
+ * Called at the write site and not before. `installedHarnessVersion` memoizes,
+ * so a multi-class command that registers once and a session that reaches this
+ * twice both pay at most one probe per process.
+ */
+function registrationProvenance(run) {
+    return harnessProvenance(run.harness, run.eventVersion);
+}
+/**
+ * Withdraw every still-pending key this invocation OPENED (APRV-106, narrowed
+ * by APRV-117).
+ *
+ * BEST EFFORT, always. The caller has already decided what verdict it is
+ * printing; this only decides whether a human is still going to be asked about
+ * it. A withdrawal that refuses is reported on stderr and changes nothing —
+ * including the case that matters most, `already-decided`, which means a human
+ * answered while this was running and their answer must not be touched.
+ *
+ * Two things narrowed under APRV-117, and both are load-bearing.
+ *
+ * **The timeout no longer calls this immediately.** A request keyed by payload
+ * hash can be adopted by the retry, so an answer that lands after this process
+ * gave up still authorizes something; retracting it at once would be throwing
+ * away the very decision the human is about to make. What still calls this is
+ * every path where nothing will retry: a signal, a thrown failure, an intake
+ * refusal that dooms the whole command, and — since APRV-287 — a wait whose
+ * retry grace has run out (see {@link withdrawAbandoned}).
+ *
+ * **Only keys this invocation opened.** An ADOPTED key was requested by another
+ * process, and `withdraw` is requester-only by design (APRV-106 rule 1): taking
+ * back a question somebody else asked is exactly the queue-clearing the gate
+ * refuses. So adopted keys are never passed here.
+ *
+ * Returns the keys actually withdrawn, for the deny reason.
+ */
+function withdrawPending(run, streams, keys, why, reason = "cancelled") {
+    const withdrawn = [];
+    for (const key of keys) {
+        const result = withdraw(run.logPath, key, run.actor, {
+            ...run.options,
+            reason,
+            note: why,
+        });
+        if (result.ok) {
+            withdrawn.push(key);
+            continue;
+        }
+        if (result.code === "already-decided" || result.code === "request-withdrawn")
+            continue;
+        streams.err(`approval: the hook could not withdraw ${key} (${result.code}): ${result.message}\n`);
+    }
+    return withdrawn;
+}
+/**
+ * Pending harness requests this actor opened that nothing will ever adopt
+ * (APRV-287).
+ *
+ * ## The state this names
+ *
+ * A wait that expires leaves its question open, because a decision inside the
+ * policy's TTL still authorizes an identical retry (APRV-117). That is right
+ * for as long as a retry is plausible and wrong afterwards: on 2026-09-06 three
+ * waits expired behind a dead daemon, nothing retried them, and the requests sat
+ * live until the TTL — so the daemon's restart re-delivered a dozen dead
+ * questions to a phone, one message each. The grace window
+ * (`core/harness-wait.ts`) is where the two readings meet: inside it the
+ * question is live for the retry, past it the asker is gone.
+ *
+ * ## What it will not name
+ *
+ *  - **A request another actor opened.** `withdraw` is requester-only by design
+ *    (APRV-106 rule 1), so the filter is the same fact stated before the call:
+ *    taking back somebody else's question is the queue-clearing the gate
+ *    refuses.
+ *  - **The bytes this invocation is asking about.** `keepHash` is this
+ *    invocation's payload hash, and a request carrying it is the question this
+ *    process is adopting or waiting on. Sweeping it would be a hook withdrawing
+ *    its own live question.
+ *  - **Anything but a live `approval.requested`.** The state is derived through
+ *    `requestState` from the verified records the caller already read, so a
+ *    decided, expired or already withdrawn request is never touched.
+ *  - **A request younger than the wait plus the grace**, measured from the
+ *    `approval.requested` record's own runtime-assigned timestamp.
+ *
+ * Nothing here appends: the caller decides what to do with the list, and the
+ * append happens through {@link withdrawPending} like every other withdrawal on
+ * this surface.
+ */
+function abandonedRequests(run, records, now, keepHash) {
+    const nowMs = Date.parse(now);
+    if (Number.isNaN(nowMs))
+        return [];
+    const limit = abandonedAfterMs(run.timeoutMs, run.graceMs);
+    const found = new Map();
+    for (const record of records) {
+        if (record.event !== "approval.requested")
+            continue;
+        if (record.actor !== run.actor)
+            continue;
+        const key = record.action_key;
+        if (typeof key !== "string" || key.length === 0)
+            continue;
+        const payload = payloadOf(record);
+        if (payload["execution"] !== "harness")
+            continue;
+        if (keepHash !== null && payload["payload_hash"] === keepHash)
+            continue;
+        const at = Date.parse(record.ts);
+        if (Number.isNaN(at) || nowMs - at < limit)
+            continue;
+        if (requestState(records, key, now, run.ttlMs).state !== "requested")
+            continue;
+        const cls = payload["class"];
+        found.set(key, {
+            actionKey: key,
+            cls: typeof cls === "string" ? cls : "(no class)",
+            ageMs: nowMs - at,
+        });
+    }
+    return [...found.values()];
+}
+/** Minutes, for a sentence a human reads. */
+function minutesText(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes >= 1)
+        return `${String(minutes)}m`;
+    return `${String(Math.max(1, Math.round(ms / 1000)))}s`;
+}
+/**
+ * Take back every question this actor opened that the grace window has run out
+ * on (APRV-287).
+ *
+ * Best effort, exactly as {@link withdrawPending} is: a withdrawal that refuses
+ * changes nothing, and `already-decided` — a human answering while this ran —
+ * is passed over in silence there. Returns the keys actually withdrawn.
+ */
+function withdrawAbandoned(run, streams, records, now, keepHash, only = null) {
+    const abandoned = abandonedRequests(run, records, now, keepHash).filter((entry) => only === null || only.includes(entry.actionKey));
+    if (abandoned.length === 0)
+        return [];
+    return withdrawPending(run, streams, abandoned.map((entry) => entry.actionKey), `no retry adopted this question within ${minutesText(abandonedAfterMs(run.timeoutMs, run.graceMs))} of the hook's wait opening it (APRV-287); the asking tool call is gone, so the request is taken back rather than left for a listener to re-deliver`, "timeout");
+}
+/**
+ * Spend every grant this verdict rests on, once each (APRV-117).
+ *
+ * A harness grant mints no token, so the record that it was used has to be
+ * written deliberately: `consumeHarnessGrant` appends one `execution.started`
+ * per key, through compare-and-append, and refuses `already-executed` if
+ * anything spent it first. Called ONLY immediately before an `allow`, so a
+ * verdict of deny spends nothing.
+ *
+ * Returns `null` on success, or the refusal that stopped it. A multi-class
+ * command can consume its first key and fail on its second; the result is a
+ * DENY with the first grant spent, which costs one extra prompt on the retry
+ * and authorizes nothing. The reverse ordering — allow first, record later —
+ * would trade that for a grant the harness used and the log never saw, so the
+ * cheap failure is the correct one.
+ *
+ * `hash` is the binding the caller already computed over the bytes this verdict
+ * is about (APRV-146). The gate requires it and compares it against what the
+ * human answered: the same value keyed the carryover that found these grants, so
+ * presenting it states, at the spend, the fact the match was made on.
+ */
+function consumeGrants(run, keys, hash, 
+/**
+ * This invocation's own task id (APRV-200). The gate compares it against the
+ * task the request record carries and records `grant_origin: "direct"` only
+ * when they are the same tool call; anything else records `carried`.
+ */
+task) {
+    for (const key of keys) {
+        const spent = consumeHarnessGrant(run.logPath, key, run.actor, {
+            ...run.options,
+            presentedPayloadHash: hash,
+            spendingTask: task,
+        });
+        if (!spent.ok)
+            return { code: spent.code, message: `${key}: ${spent.message}` };
+    }
+    return null;
+}
+/**
+ * Establish, from the VERIFIED log, that every grant this verdict rests on is
+ * spent and recorded — before the allow is printed (APRV-200).
+ *
+ * ## Why a second read
+ *
+ * {@link consumeGrants} appends through compare-and-append and reports what the
+ * gate returned, which is the write side of §11.1 invariant 8. This is the read
+ * side, and on this surface it is not redundant. Everywhere else in the runtime
+ * the process that appends `execution.started` is the process that then performs
+ * the side effect, so an append that returned success is an append the same
+ * process is about to act on. Here the executor is the HARNESS: the hook prints
+ * `allow` and a different program does the thing. What that program is authorized
+ * by is not the gate's return value, which it never sees; it is the record. So
+ * the record is what the hook checks, through the same verified path every
+ * enforcement read in this module uses (§11.1 invariant 1), and a verdict is
+ * printed only once the chain carries it.
+ *
+ * A failure here denies with the grant already spent. That is the fail-closed
+ * direction and the same trade `consumeGrants` documents: the retry costs one
+ * more prompt and authorizes nothing, where the reverse ordering would hand the
+ * harness a permission the log cannot show.
+ */
+function verifySpent(run, keys) {
+    const read = readVerifiedRecords(run.logPath);
+    if (!read.ok) {
+        return {
+            code: "hook-grant-unverified",
+            detail: `the grant(s) for ${keys.join(", ")} were spent, but the log could not be re-read verified afterwards (${read.message}), so this hook cannot show that the record authorizing the tool call is in the chain. Nothing is allowed on an authorization the log cannot be seen to carry.`,
+        };
+    }
+    const missing = keys.filter((key) => !read.records.some((record) => record.event === "execution.started" && record.action_key === key));
+    if (missing.length === 0)
+        return null;
+    return {
+        code: "hook-grant-unverified",
+        detail: `the spend of ${missing.join(", ")} reported success and the verified log does not carry its execution.started; the tool call is denied rather than allowed on a record that is not there.`,
+    };
+}
+/**
+ * What the runtime must establish from the VERIFIED log before the hook lets a
+ * command run with no human anywhere in the loop (APRV-139).
+ *
+ * The hole this closes. Until this check the hook's autonomous verdict was
+ * computed from the on-disk policy alone: `loadPolicy`, `resolve`, allow. No
+ * attestation, no loop-escalation, nothing appended, nothing read. Because the
+ * harness — not this runtime — executes the tool call on an allow,
+ * `core/execute.ts`'s own guards were never reached either, so whoever could
+ * write APPROVAL.md (a merge, a second agent, a branch checkout) could
+ * reclassify any class to `autonomous` and the hook would let the command
+ * through. SPEC.md §11.1 says the opposite: an edited policy is inoperative
+ * until a human re-attests it, and the hook is an enforcement surface like any
+ * other.
+ *
+ * The two facts checked here are exactly the two `core/execute.ts`'s
+ * supervised/autonomous branch checks before it starts one, and they are
+ * checked in the same order, against a log read the same way:
+ *
+ *  1. the live policy bytes match the latest attestation (`core/attest.ts`);
+ *  2. the task is not loop-escalated (SPEC.md §10.2, `core/loop.ts`).
+ *
+ * **Where a failure lands.** Both refusals are the gate's own frozen codes,
+ * emitted through the `hook-gate-refused:` family, and they are the verdict the
+ * gated path would have printed for these classes anyway: `core/gate.ts`'s
+ * `request` checks attestation before it resolves anything, and refuses a
+ * non-manual class for an escalated task. Checking here rather than there means
+ * the deny costs no `task.registered` — under an unattested policy every
+ * autonomous command an agent runs would otherwise append one, which is a log
+ * full of registrations written under rules nobody is enforcing.
+ *
+ * **Only where nobody is asked.** The caller runs this when EVERY class resolves
+ * non-manual. A command with a manual class keeps its existing path: escalation
+ * escalates *to* manual rather than closing the task (`core/loop.ts`), and
+ * refusing the human's question too would leave an escalated task with no way
+ * back.
+ */
+function unattendedGuard(logPath, policyPath, task, 
+/**
+ * Records this invocation has ALREADY read and verified (APRV-214). The
+ * window lookup near the top of `runHarnessHook` performs a verified read
+ * before the policy is loaded, and handing its result down means the closed
+ * path still costs one verified read rather than gaining a third (APRV-209).
+ * `null` where that read did not happen or did not verify, and then this does
+ * its own, exactly as it always did.
+ */
+known = null) {
+    // The VERIFIED log, as every enforcement path reads it (SPEC.md §11.1): an
+    // attestation or a failure streak read off unverified bytes is whatever the
+    // last writer of the file wanted it to be.
+    const read = known === null ? readVerifiedRecords(logPath) : { ok: true, records: known };
+    if (!read.ok)
+        return { code: "hook-io", detail: read.message };
+    const refusal = attestationRefusal(checkAttestation(read.records, policyPath));
+    if (refusal !== null) {
+        return {
+            code: `hook-gate-refused:${refusal.code}`,
+            detail: `${refusal.message}. Until then the hook decides nothing unattended: this command would have run with no human in the loop under rules no human has vouched for.`,
+        };
+    }
+    if (isLoopEscalated(read.records, task)) {
+        return {
+            code: "hook-gate-refused:loop-escalated",
+            detail: `loop-escalated: task ${task} has three consecutive failed side-effecting executions and is escalated to manual (amended SPEC.md §10.2), so its unattended classes may not run. ${loopClearance("task", task)}.`,
+        };
+    }
+    return null;
+}
+/**
+ * Is this tool call floored to manual by a harness streak (APRV-145)?
+ *
+ * The VERIFIED log, like every other enforcement read in this module: a failure
+ * streak computed off unverified bytes is whatever the last writer of the file
+ * wanted it to be (§11.1 invariant 1). A log this hook cannot read fails closed
+ * as a deny at the call site rather than as "no floor", because "we could not
+ * establish the streak" is not "there is no streak".
+ *
+ * Both scopes are derived inside `core/loop.ts` from the task id this runtime
+ * minted and the identity this process runs as. Nothing on the event names the
+ * bucket it is counted in, which is what stops an agent shedding a streak by
+ * rotating a string.
+ */
+function harnessFloor(logPath, task, actor, 
+/** Already-verified records from this invocation's window lookup (APRV-214). */
+known = null) {
+    if (known !== null)
+        return { ok: true, floor: harnessLoopFloor(known, task, actor) };
+    const read = readVerifiedRecords(logPath);
+    if (!read.ok)
+        return { ok: false, detail: read.message };
+    return { ok: true, floor: harnessLoopFloor(read.records, task, actor) };
+}
+/**
+ * Charge and record every class of an unattended allow (APRV-141).
+ *
+ * One `execution.started` per class, through `core/gate.ts`, before the allow
+ * is printed. Until this, a supervised or autonomous harness verdict appended
+ * nothing at all, so `core/budgets.ts` charged it nothing (`daily_actions`
+ * included) and `core/audit.ts` could never sample it — under Claude Code, on
+ * the path that carries most of the traffic. The comment that path used to
+ * carry was right that a record per agent action fills the log; APRV-141's
+ * recorded decision is that an uncharged, unsampleable majority is the worse
+ * of the two, and the record is kept as small as the contract allows.
+ *
+ * **The order is record-then-allow, and the failure is a deny.** A verdict
+ * printed before the charge landed is a command that ran outside every budget,
+ * which is the hole this closes. A refusal here (a budget ceiling, a head that
+ * moved) therefore denies, and reaches the caller as the gate's own code.
+ *
+ * The autonomous classes are recorded with no `task.registered` behind them,
+ * deliberately: `core/audit.ts` samples supervised executions only, so a
+ * declaration would buy no oversight and would double the volume of exactly the
+ * traffic this is trying not to drown the log in. The supervised classes are
+ * registered already, by the caller, which is what makes them sampleable.
+ */
+function recordUnattended(run, task, classes, hash) {
+    for (const cls of classes) {
+        const started = startHarnessExecution(run.logPath, { task, actionKey: `${task}:${cls}`, cls, payload_hash: hash }, run.actor, run.options);
+        if (!started.ok)
+            return { code: started.code, message: `${cls}: ${started.message}` };
+    }
+    return null;
+}
+/**
+ * Say, on STDERR, that a question is now on a human's queue and where it went
+ * (APRV-281).
+ *
+ * The behaviour this replaces: a gated tool call appended its request and then
+ * blocked for the whole wait in complete silence, ending in a `hook-timeout` the
+ * agent read as a refusal and the operator never saw coming. Nine minutes of a
+ * session's clock, with no way to tell "nobody has answered yet" from "nothing
+ * is even delivering this".
+ *
+ * **STDERR, and never stdout.** Stdout carries the verdict object the harness
+ * parses (see this file's header); a second object, or any prose at all, on that
+ * stream is a hook the harness cannot read. Claude Code shows stderr to the
+ * operator, which is exactly the audience for this.
+ *
+ * **It decides nothing.** No verdict, no timeout, no record, no refusal code
+ * turns on any of it. Both lines are printed after the request is appended and
+ * before the poll loop starts, so the state they describe is the state that
+ * exists; a probe that reported nothing (an unreadable directory, a platform
+ * with no euid) simply stays quiet rather than changing what this process does.
+ *
+ * **The listener line names a socket, and claims only what a socket can tell
+ * you.** `drawSocketUsable` is the same predicate an asker consults, and this
+ * connects to nothing: a usable-looking socket therefore prints NOTHING here,
+ * because a `stat` cannot establish that the far side answers. What an absent
+ * or untrustworthy socket does establish is that `approval up` is not running
+ * against this log in this checkout, and `approval up` is the one process that
+ * both serves the channels and consumes the taps. That is worth saying: on
+ * 2026-09-05 taps piled up unconsumed while hooks waited out their windows.
+ */
+function announceWait(streams, run, waiting) {
+    const where = run.channels.length === 0
+        ? "no channel (this policy configures none, so nothing is delivering the question)"
+        : `channel ${run.channels.join(", ")}`;
+    for (const action of waiting) {
+        const adopted = action.origin === "adopted"
+            ? " The question was already open for these exact bytes, so this tool call adopts it rather than asking a second time."
+            : "";
+        streams.err(`approval: ${action.actionKey} (${action.cls}) is waiting for a human on ${where}; a decision on the phone releases it, and this hook blocks for up to ${String(run.timeoutMs)}ms before denying with hook-timeout and leaving the request open for a ${minutesText(run.graceMs)} retry grace.${adopted}\n`);
+    }
+    const socket = drawSocketPathFor(run.logPath);
+    const listener = drawSocketUsable(socket);
+    if (listener.ok)
+        return;
+    streams.err(`approval: no listener is running for this log (${listener.reason}: ${socket}), so the request above may sit undelivered and a decision may go unconsumed. Start the gate's ambient runtime in the checkout that owns this log: \`eval "$(approval env)" && approval up\`, which runs the daemon loop and every configured channel in one process.\n`);
+}
+/**
+ * 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.
+ */
+function gateAndWait(streams, run, classes, 
+/**
+ * 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, headline, 
+/**
+ * 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, 
+/** The history-rewrite refinement's own words, or `""` (APRV-108). */
+note = "", 
+/**
+ * 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 = null) {
+    /**
+     * Does the floor route THIS class to a human? (APRV-297.)
+     *
+     * Per class rather than per command, because a MIXED tool call is one question
+     * about its side effects and no question at all about its looking. Under a
+     * floor, `ls -la && mkdir build` raises the write and leaves the read to the
+     * policy, so the approver sees one prompt for what the command DOES. Before
+     * this the read class was raised too, and a floored session put two prompts on
+     * a phone for one command, one of which nobody needed to answer.
+     *
+     * The command is still routed as a whole: the verdict waits on the classes
+     * that were raised, and an allow covers the command.
+     */
+    const floorApplies = (cls) => floor !== null && isSideEffectingClass(cls);
+    const hash = payloadHash(payload);
+    const summary = truncate(headline, SUMMARY_LIMIT);
+    const sayAllow = (reason) => allow(streams, reason, run.harness);
+    /**
+     * Every deny this function can print, with the floor's own sentence appended
+     * when a floor is what routed the command here (APRV-280). One wrapper rather
+     * than a sentence bolted onto the timeout alone: a floored invocation that
+     * ends in a rejection, a lapse or an I/O fault leaves the agent in exactly the
+     * same place, and the operator reading the harness's error stream needs the
+     * scope key either way.
+     */
+    const sayDeny = (code, detail) => deny(streams, code, floor === null
+        ? detail
+        : `${detail} This tool call was routed to a human by loop safety rather than by policy — loop-escalated: ${floor.scope} ${floor.key} has ${String(floor.consecutiveFailures)} consecutive failed side-effecting harness tool calls (amended SPEC.md §10.2). ${loopClearance(floor.scope, floor.key)}`, run.harness);
+    // Intake reads the VERIFIED log, once, before anything is written: an
+    // enforcement path reads nothing else (SPEC.md §11.1), and a carry decided
+    // from unverified bytes would be a grant invented by whoever could write the
+    // file.
+    const intake = readVerifiedRecords(run.logPath);
+    if (!intake.ok)
+        return sayDeny("hook-io", intake.message);
+    const intakeTs = new Date().toISOString();
+    // APRV-287. Before this invocation adds a question of its own, the questions
+    // earlier invocations of this actor left behind are taken back — every one
+    // whose grace window has run out, and never the bytes this one is about to
+    // ask about. The hook is the only writer that can do this: `withdraw` is
+    // requester-only, and the requester of a harness request is this actor.
+    const swept = withdrawAbandoned(run, streams, intake.records, intakeTs, hash);
+    if (swept.length > 0) {
+        streams.err(`approval: withdrew ${String(swept.length)} abandoned harness request(s) nothing retried (${swept.join(", ")}); a tap on one of them now authorizes nothing and the channel says so\n`);
+    }
+    const actions = classes.map((cls) => {
+        const carry = findHarnessCarry(intake.records, hash, cls, intakeTs, run.ttlMs);
+        if (carry === null)
+            return { cls, actionKey: `${task}:${cls}`, origin: "new" };
+        return {
+            cls,
+            actionKey: carry.actionKey,
+            origin: carry.kind === "granted" ? "carried" : "adopted",
+        };
+    });
+    const fresh = actions.filter((action) => action.origin === "new");
+    const adopted = actions.filter((action) => action.origin === "adopted");
+    const carried = actions.filter((action) => action.origin === "carried");
+    // Only the classes that need a new question are registered. A retry whose
+    // every class carries or adopts registers no task at all — the envelope it
+    // would declare already exists, under the key it is about to wait on.
+    if (fresh.length > 0) {
+        const envelope = {
+            origin: { app: run.originApp, created_by: run.actor },
+            state: "proposed",
+            actions: fresh.map((action) => ({
+                class: action.cls,
+                summary,
+                idempotency_key: action.actionKey,
+                payload_hash: hash,
+            })),
+        };
+        // APRV-227: which harness binary wrote this registration. A CALL option,
+        // never a field of the envelope above — an envelope is authored by the
+        // party under oversight, and this is a statement about the binary doing
+        // the overseeing.
+        const provenance = registrationProvenance(run);
+        const registered = register(run.logPath, { task, envelope }, run.actor, {
+            ...run.options,
+            ...(provenance === null ? {} : { harness: provenance }),
+        });
+        if (!registered.ok) {
+            return sayDeny(`hook-gate-refused:${registered.code}`, registered.message);
+        }
+    }
+    // `execution: "harness"` says a grant here mints no execution token. The hook
+    // answers allow/deny and Claude Code runs the command; nothing ever calls
+    // `approval run`, so a minted token would be a live credential with no
+    // spender. It removes capability from the requester and grants none.
+    //
+    // APRV-106's companion field, `wait_until`, is deliberately NOT declared any
+    // more. It rendered as "requester waits until 09:23 UTC" on the approver's
+    // phone, and under carryover that sentence is false: an answer after this
+    // invocation stops waiting authorizes the retry. With no `wait_until` the
+    // channel's own line falls back to the deadline that does govern — "expires
+    // HH:MM UTC", the policy's TTL — which is now exactly the truth.
+    const ownKeys = [];
+    for (const action of fresh) {
+        const result = request(run.logPath, {
+            task,
+            actionKey: action.actionKey,
+            cls: action.cls,
+            summary,
+            payload_hash: hash,
+            payload: { value: payload },
+            execution: "harness",
+            ...(floorApplies(action.cls) ? { loopFloor: true } : {}),
+        }, run.actor, run.options);
+        if (!result.ok) {
+            // Whatever this invocation opened is retracted before the deny: a refusal
+            // on the third class dooms the command on every retry too, so the first
+            // two must not stand in a queue that nothing will ever adopt.
+            withdrawPending(run, streams, ownKeys, `intake refused ${action.actionKey}; this command cannot proceed, so the classes already opened for it are questions nobody needs to answer`);
+            return sayDeny(`hook-gate-refused:${result.code}`, result.message);
+        }
+        if (result.record !== null)
+            ownKeys.push(action.actionKey);
+    }
+    /** Every key that must be granted before this hook says yes. */
+    const waitKeys = [...adopted.map((action) => action.actionKey), ...ownKeys];
+    /** Every key whose grant this verdict would spend. */
+    const spendKeys = [...carried.map((action) => action.actionKey), ...waitKeys];
+    /** How the allow line describes where its authorization came from. */
+    const provenance = carried.length === 0
+        ? ""
+        : ` (carried: ${carried.map((action) => action.actionKey).join(", ")})`;
+    if (waitKeys.length === 0) {
+        if (spendKeys.length === 0) {
+            // Every class resolved supervised: intake recorded no request (amended
+            // SPEC.md §6.3), so there is nothing to wait for and nothing to spend.
+            // What there is, since APRV-141, is something to charge: the start event
+            // is this execution's authorization, and the registration `fresh` just
+            // wrote is what makes it a sampleable one.
+            const charged = recordUnattended(run, task, classes, hash);
+            if (charged !== null) {
+                return sayDeny(`hook-gate-refused:${charged.code}`, charged.message);
+            }
+            return sayAllow(`granted: ${classes.join(", ")} needs no approval under this policy${note}`);
+        }
+        // Every gated class carried an unspent grant: a human already answered this
+        // exact question about these exact bytes, and nobody is asked again.
+        const failed = consumeGrants(run, spendKeys, hash, task);
+        if (failed !== null) {
+            return sayDeny(`hook-gate-refused:${failed.code}`, failed.message);
+        }
+        const unverified = verifySpent(run, spendKeys);
+        if (unverified !== null)
+            return sayDeny(unverified.code, unverified.detail);
+        return sayAllow(`granted: ${classes.join(", ")}${provenance}${note}`);
+    }
+    // Past every early return, so this is reached only where this process is
+    // genuinely about to block on a human (APRV-281). The set it names is the set
+    // it waits on: the keys this invocation opened, plus the ones it adopted from
+    // an earlier tool call, which wait in the same silence and were the case the
+    // announce would most easily have missed. A carried grant is not here because
+    // nothing is waiting on it.
+    announceWait(streams, run, actions.filter((action) => waitKeys.includes(action.actionKey)));
+    const deadline = Date.now() + run.timeoutMs;
+    // A signal arriving mid-wait means the session is going away: nothing will
+    // retry this command, so the question this invocation opened is retracted.
+    // `process.exit` is deliberate and immediate: the default disposition for
+    // these signals is to die, and a handler that only withdrew would leave the
+    // hook wedged in its poll loop with the harness waiting on it.
+    const onSignal = (signal) => {
+        withdrawPending(run, streams, ownKeys, `the requesting hook process received ${signal} while waiting; the session is ending, so no retry will adopt this request`);
+        process.exit(EXIT_USAGE);
+    };
+    const onTerm = () => onSignal("SIGTERM");
+    const onInt = () => onSignal("SIGINT");
+    process.on("SIGTERM", onTerm);
+    process.on("SIGINT", onInt);
+    /**
+     * Has this invocation already said, on stderr, that the verified view lags
+     * the requests it is waiting on (APRV-294)? Said once per invocation: the
+     * poll runs every second, and a line per poll would bury the one line that
+     * matters under sixty copies of itself.
+     */
+    let saidLagging = false;
+    try {
+        for (;;) {
+            const read = readVerifiedRecords(run.logPath);
+            if (!read.ok) {
+                withdrawPending(run, streams, ownKeys, `the hook could not read the log while waiting on ${task}`);
+                return sayDeny("hook-io", read.message);
+            }
+            const ts = new Date().toISOString();
+            // Only the keys this invocation is waiting on count. Deriving the set
+            // from the log again would let an empty or foreign result read as
+            // "nothing pending" and fall through to allow; the verified log must show
+            // every one of these keys granted before the hook says yes.
+            const derived = waitKeys.map((key) => ({
+                key,
+                state: requestState(read.records, key, ts, run.ttlMs).state,
+            }));
+            const states = derived.map((entry) => entry.state);
+            /**
+             * Keys this process ESTABLISHED exist, that this read does not carry
+             * (APRV-294).
+             *
+             * Every key in `waitKeys` was seen in a verified read by this process:
+             * `ownKeys` because `request` appended it and returned the record,
+             * `adopted` because intake's verified read found the pending request it
+             * is adopting. So `none` here is never the terminal fact "there is no
+             * such request". A log is append-only; a request that existed does not
+             * stop existing. What `none` says is that the view this read produced
+             * does not yet carry a record this process holds, which is a fact about
+             * the view and not about the request.
+             *
+             * On 2026-09-07 02:00Z, minutes after `approval log sync` replaced the
+             * committed baseline and the daemon restarted, a hook read exactly this
+             * and denied at once: `hook-io: the verified log does not show every
+             * request as granted (states: none, none, none)`. The requests were real
+             * and reached the approver's phone; the view had not caught up. Treating
+             * that as terminal spends the human's answer on nothing and, since it is
+             * a deny, hands the agent a refusal for a question still open.
+             *
+             * So a lagging key waits, exactly as `requested` waits, bounded by the
+             * same timeout — and nothing here reads unverified bytes as verified,
+             * which is the only response to a lag that §11.1 invariant 1 leaves open.
+             * The APRV-287 withdrawal still applies at expiry, over the keys whose
+             * requests the view does carry.
+             */
+            const lagging = derived
+                .filter((entry) => entry.state === "none")
+                .map((entry) => entry.key);
+            if (lagging.length > 0 && !saidLagging) {
+                saidLagging = true;
+                streams.err(`approval: the verified log does not yet carry ${lagging.join(", ")} (verified head: ${read.head === null ? "empty" : `seq ${String(read.head.seq)}`}). The request(s) were appended by this hook, so this is a view that lags rather than a decision; the hook keeps waiting for the verification to catch up, up to its ${String(run.timeoutMs)}ms wait. A sync or a daemon restart in the last minute is the usual cause (docs/claude-code-hook.md).\n`);
+            }
+            if (!states.includes("requested") && lagging.length === 0) {
+                // Precedence, as `approval wait` fixes it: a human's "no" outranks a
+                // lapse, and both outrank "everything was granted". A withdrawal sits
+                // with the refusals: it is not a decision, but it is terminal, and it
+                // means this key will never be granted.
+                if (states.includes("rejected")) {
+                    return sayDeny("hook-rejected", `a human rejected ${task}`);
+                }
+                if (states.includes("revoked")) {
+                    return sayDeny("hook-revoked", `approval for ${task} was withdrawn`);
+                }
+                if (states.includes("withdrawn")) {
+                    return sayDeny("hook-withdrawn", `the request for ${task} was withdrawn before a decision; nothing is pending and nothing was authorized`);
+                }
+                if (states.includes("expired")) {
+                    return sayDeny("hook-expired", `the request for ${task} lapsed before a decision`);
+                }
+                if (states.every((state) => state === "granted")) {
+                    // The grants are spent before the allow is printed, so this exact
+                    // command cannot ride the same authorization twice.
+                    const failed = consumeGrants(run, spendKeys, hash, task);
+                    if (failed !== null) {
+                        return sayDeny(`hook-gate-refused:${failed.code}`, failed.message);
+                    }
+                    const unverified = verifySpent(run, spendKeys);
+                    if (unverified !== null)
+                        return sayDeny(unverified.code, unverified.detail);
+                    return sayAllow(`granted: ${task} (${classes.join(", ")})${provenance}${note}`);
+                }
+                // Not a wait outcome: the log disagrees with itself about keys this
+                // process is waiting on. Nothing is retracted, because the state that
+                // would justify retracting is the state that could not be established.
+                //
+                // A BACKSTOP since APRV-294, and deliberately kept. `none` no longer
+                // reaches here (it waits, above) and every remaining state is either
+                // terminal and answered above or `granted`, so this is unreachable
+                // through today's `RequestState`. It stands for the state a later
+                // member of that union would arrive as: an outcome this function has no
+                // reading for denies rather than allows.
+                return sayDeny("hook-io", `the verified log does not show every request for ${task} as granted (states: ${states.join(", ")})`);
+            }
+            if (Date.now() >= deadline) {
+                // APRV-117, narrowed by APRV-287. The request stays open for the RETRY
+                // GRACE: a decision inside that window authorizes the retry of this
+                // exact command in this exact directory, once, and withdrawing at the
+                // first expiry would discard the answer the human is about to give.
+                // Past the grace nobody is coming back for it, and a question nothing
+                // will adopt is taken back rather than left for a restarted listener to
+                // re-deliver.
+                const withdrawn = withdrawAbandoned(run, streams, read.records, ts, null, ownKeys);
+                // APRV-294: a wait that ends with the view still short of its own
+                // requests says so. The deny is the same deny — the wait ran out — and
+                // the repair is different from a queue nobody answered: the log this
+                // hook reads is behind the log it wrote to, and `approval log verify`
+                // in the checkout that owns it is where that is established.
+                const stillLagging = lagging.length === 0
+                    ? ""
+                    : ` The verified view still does not carry ${lagging.join(", ")}, which this hook appended: the request(s) exist and the view is behind, so check the log that owns them (\`approval log verify\`, \`approval status\`) rather than reading this as an unanswered question.`;
+                if (withdrawn.length > 0) {
+                    return sayDeny("hook-timeout", `no decision on ${waitKeys.join(", ")} within the hook's ${String(run.timeoutMs)}ms wait, and the ${minutesText(run.graceMs)} retry grace has run out: ${withdrawn.join(", ")} WAS WITHDRAWN (reason timeout). A tap on it now authorizes nothing and the channel says so. Run the command again to ask the question fresh.${stillLagging}`);
+                }
+                return sayDeny("hook-timeout", `no decision on ${waitKeys.join(", ")} within the hook's ${String(run.timeoutMs)}ms wait. This tool call is denied and NOTHING WAS WITHDRAWN: the request(s) stay open for the ${minutesText(run.graceMs)} retry grace, and a decision inside that window authorizes a retry of this exact command in this exact directory, once. Retry it after the approver answers; the retry adopts the same question rather than asking a second one. Past the grace the hook takes the question back (approval.withdrawn, reason timeout), so a late retry asks again rather than adopting a question nobody is holding.${stillLagging}`);
+            }
+            sleepSync(Math.min(run.intervalMs, Math.max(0, deadline - Date.now())));
+        }
+    }
+    catch (cause) {
+        // The thrown path. `commandHarnessHook` turns this into an ordinary
+        // deny. Unlike the timeout, this process cannot say what state it left
+        // behind, so the question it opened is retracted rather than left standing
+        // on a failure nobody diagnosed.
+        withdrawPending(run, streams, ownKeys, `the requesting hook process failed while waiting (${cause instanceof Error ? cause.message : String(cause)})`);
+        throw cause;
+    }
+    finally {
+        process.off("SIGTERM", onTerm);
+        process.off("SIGINT", onInt);
+    }
+}
+// ===========================================================================
+// The completion counterpart (APRV-145)
+// ===========================================================================
+/**
+ * The hook event names that report a tool call's OUTCOME rather than ask about
+ * it, from `docs/claude-code-hook.md`'s pinned contract.
+ *
+ * `PostToolUseFailure` is listed because Claude Code splits the report in two:
+ * a tool call that failed outright fires it instead of `PostToolUse`, and a
+ * counterpart that only knew the success event would record the completions and
+ * silently drop every failure, which is the one direction §11.1 invariant 4
+ * forbids.
+ */
+const POST_TOOL_EVENTS = ["PostToolUse", "PostToolUseFailure"];
+/**
+ * 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 const POST_TOOL_CODES = [
+    /** 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",
+];
+/** The one code that means the counterpart landed, and the one that exits 0. */
+const POST_TOOL_REPORTED = "post-tool-reported";
+/**
+ * The exit code that makes a post-execution hook's stderr visible (APRV-303).
+ *
+ * It is the number Claude Code's hook protocol reserves for "show this line",
+ * and on this one path it means exactly that. It is NOT `EXIT_USAGE`, whose
+ * meaning in `cli/exit-codes.ts` is a malformed invocation: the harness hooks
+ * speak the harness's protocol on both streams already (stdout carries a
+ * decision object no other verb prints), and the exit code is the third field
+ * of that same protocol. Nothing branches on it inside this runtime.
+ */
+const POST_TOOL_SURFACE_EXIT = 2;
+/**
+ * One machine-readable line on stderr. Never a verdict, and never blocking.
+ *
+ * Exit 0 for the report that landed, {@link POST_TOOL_SURFACE_EXIT} for every
+ * other code, so that a report which did NOT land is seen rather than written
+ * to a debug log nobody opens (see {@link POST_TOOL_CODES}).
+ */
+function report(streams, code, detail, extra = {}) {
+    streams.err(`${JSON.stringify({ approval: { hook: "post-tool-use", code, detail, ...extra } })}\n`);
+    return code === POST_TOOL_REPORTED ? EXIT_OK : POST_TOOL_SURFACE_EXIT;
+}
+/**
+ * Read a tool call's outcome off the reporting event, by a CLOSED set of
+ * readings.
+ *
+ * ## THE EVENT NAME IS THE OUTCOME (APRV-303)
+ *
+ * The reading this replaces was written against a payload Claude Code does not
+ * send. It asked for `tool_response.type` and accepted `text`, `base64` or
+ * `error`, which is the shape of an API content block. What the event actually
+ * carries under `tool_response` is the TOOL'S OWN structured output, verbatim,
+ * and the hooks reference says so in as many words. From the shipped
+ * declarations in `@anthropic-ai/claude-code/sdk-tools.d.ts`:
+ *
+ * - `BashOutput` has `stdout`, `stderr`, `interrupted`, `isImage` and no `type`;
+ * - `FileEditOutput` (Edit, MultiEdit) has `filePath`, `oldString`,
+ *   `newString`, `structuredPatch` and no `type`;
+ * - `FileWriteOutput` (Write) does have `type`, whose values are `create` and
+ *   `update`;
+ * - `NotebookEditOutput` has no `type` and an optional `error` string.
+ *
+ * So the old reading matched NOTHING a Claude Code session emits, and every
+ * successful tool call was reported unreadable and appended nothing. Measured
+ * on this project's own log on 2026-09-07: 22062 harness starts, 10 reports,
+ * and of the reports the `agent:claude-code` actor filed, nine were failures
+ * and none was a completion. The §10.2 streak became a ratchet that only ever
+ * counts up, so every long session escalated itself to manual and stayed there.
+ *
+ * The contract that IS true is the one the reference states about the events
+ * themselves. `PostToolUse` "runs immediately after a tool completes
+ * successfully". `PostToolUseFailure` runs "when a tool that started executing
+ * fails". Claude Code fires exactly one of the two, neither of them when a
+ * permission decision stopped the call before it ran. The event name is
+ * therefore the whole reading, and it is the reading with the best provenance
+ * available here: it is the harness saying which of its own two code paths ran,
+ * rather than this process inferring an outcome out of a body of text.
+ *
+ * ## The refinements, and their direction
+ *
+ * Two readings of `tool_response` sit on top, and BOTH of them only ever move
+ * the answer away from "completed" (§11.1 invariant 4: a field the reporting
+ * side authors may raise scrutiny and never lower it):
+ *
+ * - `interrupted: true` (`BashOutput`) is UNREADABLE. A command a person
+ *   interrupted neither completed nor failed on its own terms; counting it a
+ *   failure trips an escalation on somebody's ctrl-C, and counting it a
+ *   completion clears a streak on a command that never finished.
+ * - `type: "error"`, or a non-empty `error` string (`NotebookEditOutput`, and
+ *   the MCP error result the reference names) is a FAILURE, whatever the event
+ *   name claimed.
+ *
+ * Unreadable means append nothing, and that is the safe answer in both
+ * directions at once. A failure nobody observed would trip an escalation on
+ * noise, and a control that trips on noise is one operators learn to silence
+ * (§8 makes this argument about timestamp anomalies). A completion nobody
+ * observed would clear a streak on nothing. Appending nothing leaves the path
+ * exactly as vacuous as it was before this verb existed, for that tool, and
+ * manufactures neither. Since APRV-303 the unreadable arm also SAYS SO on a
+ * stream somebody reads (see {@link report}).
+ *
+ * NOTHING OF THE TOOL'S OUTPUT IS READ. Only the shape: the event name, and
+ * whether two enumerated fields are present and what kind of value they hold.
+ * No text from any of them reaches the log or this function's return.
+ */
+function readReportedOutcome(input) {
+    const event = input.hookEventName;
+    if (event !== "PostToolUse" && event !== "PostToolUseFailure") {
+        return {
+            ok: false,
+            detail: `hook_event_name is ${event === null ? "absent" : JSON.stringify(event)}, which is neither of the two events this adapter reports an outcome for (PostToolUse, PostToolUseFailure)`,
+        };
+    }
+    const response = input.toolResponse;
+    // The one thing that unreads an event of either name. `PostToolUseFailure`
+    // carries `is_interrupt` for the same fact and no `tool_response` at all, so
+    // both spellings are checked and neither is trusted to say anything else.
+    if (response?.["interrupted"] === true || input.interrupted === true) {
+        return {
+            ok: false,
+            detail: "the tool call was interrupted, so it neither completed nor failed on its own terms; an interruption is somebody stopping the session rather than a loop to escalate or a recovery to credit",
+        };
+    }
+    if (event === "PostToolUseFailure")
+        return { ok: true, outcome: "failed" };
+    const errorText = response?.["error"];
+    if (response?.["type"] === "error" ||
+        (typeof errorText === "string" && errorText.length > 0)) {
+        return { ok: true, outcome: "failed" };
+    }
+    return { ok: true, outcome: "completed" };
+}
+/**
+ * The post-execution half of `approval hook <harness>` (APRV-145).
+ *
+ * It closes the delegated `execution.started` records the pre-execution half
+ * wrote for this same tool call, so that the harness scopes of amended
+ * SPEC.md §10.2 have a failure signal to accrue at all. Everything that makes
+ * that safe lives in `core/gate.ts`'s `finishHarnessExecution`; what lives here
+ * is the reading of the event and nothing else.
+ */
+function runPostToolUse(flags, streams, cwd, input, actor, adapter) {
+    if (input.toolName !== adapter.shellTool && !adapter.fileTools.includes(input.toolName)) {
+        return report(streams, "post-tool-not-gated", `${input.toolName} is not a gated tool, so no execution.started was ever written for it`);
+    }
+    if (input.toolUseId === null) {
+        // The pre-execution half falls back to random bytes when the harness names
+        // no tool-use id, and those bytes are not recoverable from this event. The
+        // start stands, unclosed, and is counted in the coverage row of
+        // `approval status` rather than closed against a guess.
+        return report(streams, "post-tool-unidentified", "the event carries no tool_use_id, so the task id the pre-execution hook minted cannot be reconstructed; nothing was appended");
+    }
+    const reading = readReportedOutcome(input);
+    if (!reading.ok) {
+        return report(streams, "post-tool-unreadable-outcome", `${reading.detail}; nothing was appended`);
+    }
+    const { logPath, root } = hookScope(flags, cwd);
+    if (!existsSync(logPath) && !existsSync(dirname(logPath))) {
+        return report(streams, "post-tool-log-unreachable", `no log at ${logPath}; the hook writes to an existing log and never creates one. Run \`approval init\` in ${root}`);
+    }
+    const finished = finishHarnessExecution(logPath, {
+        sessionId: input.sessionId,
+        toolUseId: input.toolUseId,
+        outcome: reading.outcome,
+        // The one member of the closed set at v0.1. It names the untrusted
+        // reporter and reduces nothing.
+        reportedBy: "post-tool-use",
+    }, actor);
+    if (!finished.ok) {
+        return report(streams, `post-tool-gate-refused:${finished.code}`, finished.message);
+    }
+    return report(streams, POST_TOOL_REPORTED, `recorded ${reading.outcome} for ${String(finished.records.length)} delegated execution(s) of ${finished.task}`, { task: finished.task, outcome: reading.outcome, appended: finished.records.length });
+}
+function describeToolCall(input, adapter, protectedPaths, cwd) {
+    if (input.toolName === adapter.shellTool) {
+        const raw = readString(input.toolInput, "command");
+        if (raw === null) {
+            return {
+                kind: "deny",
+                code: "hook-io",
+                detail: `${adapter.shellTool} tool_input carries no command string`,
+            };
+        }
+        // Unchanged since APRV-117, deliberately: the payload is the WHOLE command
+        // and the directory it runs in, so the FULL PAYLOAD block on the phone
+        // carries every byte the harness will execute. Only `summary` is shortened.
+        const payload = { command: raw, cwd: input.cwd };
+        // APRV-108: a local rewrite of history this checkout never published is a
+        // commit. APRV-267: a delete confined to the agent's own scratch is not a
+        // decision. Both run in the hook's own cwd, after classification and never
+        // inside it, and neither claims anything it cannot establish from the disk.
+        const refined = classifyForHook(raw, protectedPaths, cwd);
+        const classified = refined.result;
+        if (!classified.ok) {
+            return {
+                kind: "deny",
+                code: `hook-${classified.code}`,
+                detail: `${classified.detail} (segment: ${classified.segment}). Rewrite it as a command the classifier can read, or run the effect through \`approval run\` with a granted token.`,
+            };
+        }
+        return {
+            kind: "gated",
+            classes: classified.classes.filter((cls) => cls !== GATE_SELF_CLASS),
+            payload,
+            headline: raw,
+            notes: refined.notes,
+            segments: classified.segments,
+        };
+    }
+    const gated = fileToolGate(input.toolName, input.toolInput, protectedPaths, cwd);
+    if (gated === null) {
+        return { kind: "allow", reason: `${input.toolName} names no file, so there is nothing to gate` };
+    }
+    if (!gated.protectedPath) {
+        return {
+            kind: "gated",
+            classes: [gated.cls],
+            payload: gated.payload,
+            headline: gated.summary,
+            notes: [],
+            passthrough: `${input.toolName} is not a gated edit`,
+        };
+    }
+    return {
+        kind: "gated",
+        classes: [gated.cls],
+        payload: gated.payload,
+        headline: gated.summary,
+        // The tier rides in the verdict's note as well as in the payload, so an
+        // `allow` says which checkout it authorized (APRV-124).
+        notes: [fileTierNote(gated)],
+    };
+}
+/** The environment variable that turns the sandbox requirement on (APRV-193). */
+export 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 function sandboxRequirement(segments, autonomies, env = process.env) {
+    if (env[REQUIRE_SANDBOX_ENV] !== "1")
+        return null;
+    if (segments === undefined)
+        return null;
+    if (autonomies.some((autonomy) => autonomy === "manual"))
+        return null;
+    const unwrapped = segments.filter((segment) => CODE_EXECUTING_RULES.includes(segment.rule) && segment.sandbox !== "runtime");
+    if (unwrapped.length === 0)
+        return null;
+    const first = unwrapped[0];
+    const external = first.sandbox === "external";
+    return `${REQUIRE_SANDBOX_ENV}=1, and this command runs code the runtime did not author: ${JSON.stringify(first.text)} (rule ${first.rule}), ${external ? "under a profile this runtime did not write, which is a permission you granted yourself" : "with the session's own network"}. A command like this executes whatever is in the files it names, so its class describes what was typed rather than what will happen. Re-run it as \`approval sandbox -- <command>\`: it classifies the same, it is allowed the same, and it runs with no way out to the network (docs/sandboxed-exec.md). Nothing was appended.`;
+}
+/**
+ * Is a window open over this log?
+ *
+ * Fails closed on every axis and reports NOTHING when it does. An absent log,
+ * an unreadable one, a torn tail, a chain that does not verify: each yields no
+ * window, and the caller falls through to the path it has always taken, where
+ * `hook-log-unreachable` and `hook-io` fire in the same words at the same
+ * places. A bypass derived from bytes nobody verified would be a bypass anyone
+ * able to write the file could grant themselves, which is the whole reason the
+ * window's state lives in the log rather than beside it.
+ *
+ * The existence probe is the same one the gated path makes further down, and it
+ * is made FIRST so that a hook pointed at a directory with no log does no
+ * verification work before saying so.
+ */
+function lookupWindow(logPath) {
+    if (!existsSync(logPath) && !existsSync(dirname(logPath))) {
+        return { window: null, records: null, head: null };
+    }
+    const read = readVerifiedRecords(logPath);
+    if (!read.ok)
+        return { window: null, records: null, head: null };
+    return { window: openGateWindow(read.records), records: read.records, head: read.head };
+}
+/**
+ * The banner every bypassed call prints to STDERR.
+ *
+ * Loud, and on stderr rather than in the decision reason, because the two have
+ * different readers: the reason is read by the harness and by the agent, and
+ * this is read by the person who opened the window and may have forgotten it is
+ * open. It names the seq of the record that authorized the bypass and the one
+ * that recorded it, so both ends are greppable from the log alone.
+ */
+function bypassBanner(window, classes, seq) {
+    return [
+        "!! APPROVAL GATE OPEN — this command was NOT approved !!",
+        `   window seq ${String(window.seq)}, opened by ${window.openedBy}, expires ${window.expiresAt}`,
+        `   reason: ${window.reason}`,
+        `   classes: ${classes.join(", ")}; recorded as gate.bypassed seq ${String(seq)}`,
+        "   close it with `approval gate close`",
+        "",
+    ].join("\n");
+}
+/**
+ * The bypass path: classify anyway, refuse the things the window never reaches,
+ * record the call, and only then allow it.
+ *
+ * ### What the window does NOT reach, and why each one stays
+ *
+ *  - **A command the classifier cannot read** (`hook-opaque`,
+ *    `hook-unclassified`, `hook-unparseable`). The window is a suspension of the
+ *    policy's ANSWER, and an opaque command has no question to suspend: nothing
+ *    here can establish that a `bash -c` string does not write into the log.
+ *  - **`log.mutate`.** The window suspends the policy; the log is what the
+ *    window itself is derived from, and a bypass that could rewrite the log
+ *    could rewrite its own authorization. Refused unconditionally, with no
+ *    policy consulted, because this rule is not the policy's to relax.
+ *  - **Any class the policy reserves to human hands** (§11.1 invariant 9). A
+ *    human-only class is inert to agents by construction, and a window opened by
+ *    a human does not lend an agent the human's hands.
+ *
+ * ### The policy is loaded, best-effort
+ *
+ * For the protected-path set the classifier needs, and for the human-only
+ * check. A policy that will not load is exactly the failure a window is opened
+ * to repair, so a load failure is a NOTE on the verdict rather than a refusal;
+ * the protected-path set is then empty and the human-only check has nothing to
+ * resolve against, which the note says in as many words.
+ *
+ * ### Record, then allow
+ *
+ * §11.1 invariant 8, and the same order `recordUnattended` uses: a bypassed
+ * command that ran and left no record is the one state this feature must not be
+ * able to reach, so an append failure is a deny.
+ */
+function runBypass(streams, input, adapter, cwd, logPath, flags, actor, window, 
+/**
+ * The verified read `window` was derived from (APRV-294), handed on to the
+ * append so the same records answer "is a window open" and "which head does
+ * this record chain onto". `null` is not reachable from the caller — a window
+ * implies a read that produced it — and is accepted so the seam has one
+ * shape.
+ */
+decidedOn) {
+    const scope = hookScope(flags, cwd);
+    const load = loadPolicy(scope.options.policy?.file === undefined
+        ? { dir: scope.options.policy?.dir ?? cwd }
+        : { file: scope.options.policy.file });
+    const protectedPaths = load.ok ? (load.policy.protected_paths ?? []) : [];
+    const policyNote = load.ok
+        ? null
+        : `the policy did not load (${load.code}: ${load.message}), so no protected path beyond the built-ins was known here and no class could be resolved to human-only`;
+    const described = describeToolCall(input, adapter, protectedPaths, cwd);
+    if (described.kind === "deny") {
+        return deny(streams, described.code, `${described.detail} The open window does not reach this: a command the classifier cannot read is a command nothing here can establish is safe to run unapproved.`, adapter.kind);
+    }
+    if (described.kind === "allow")
+        return allow(streams, described.reason, adapter.kind);
+    if (described.passthrough !== undefined) {
+        // APRV-303. An ordinary workspace edit is allowed by the policy on its own
+        // merits, so there is nothing here for the window to suspend and nothing
+        // for a `gate.bypassed` record to say. The only thing that would have made
+        // this call a question is a §10.2 floor, and a window bypasses the floor
+        // outright. Answered here rather than below so the bypass log stays a
+        // record of calls the window actually let through.
+        return allow(streams, described.passthrough, adapter.kind);
+    }
+    const classes = described.classes;
+    if (classes.length === 0) {
+        // The gate's own CLI, including `approval gate close`. Allowed with no
+        // record for the reason it is allowed outside a window: gating the gate
+        // with the gate recurses, and a window that recorded its own closing verb
+        // would be recording the act that ends it.
+        return allow(streams, "the approval CLI is the gate itself and is not gated by it", adapter.kind);
+    }
+    const mutation = classes.find((cls) => cls === "log.mutate");
+    if (mutation !== undefined) {
+        return deny(streams, "hook-class-human-only", `${mutation} is never reachable through the open window: the window suspends the POLICY, and the log is what the window itself is derived from. A bypass able to write the log could rewrite its own authorization. Nothing was appended; a human writes the log directory by hand or not at all.`, adapter.kind);
+    }
+    if (load.ok) {
+        const reserved = classes.find((cls) => resolvePolicy(load, cls).autonomy === "human-only");
+        if (reserved !== undefined) {
+            return deny(streams, "hook-class-human-only", `${humanOnlyRefusal(reserved, "this command may not run under an agent")} An open window does not reach it: the window suspends what the policy DECIDES, and a human-only class is one the policy reserves to human hands, which a window opened by a human does not lend to an agent (SPEC.md §11.1 invariant 9).`, adapter.kind);
+        }
+    }
+    // APRV-227, resolved here because here is where a record is written. The
+    // window path is the one a human comes back to read, so the binary that
+    // printed the allow is named on it.
+    const provenance = harnessProvenance(adapter.kind, input.harnessVersion);
+    const recorded = recordGateBypass(logPath, {
+        tool: input.toolName,
+        summary: truncate(described.headline, SUMMARY_LIMIT),
+        classes,
+        payloadHash: payloadHash(described.payload),
+        ...(input.sessionId === UNKNOWN_SESSION ? {} : { sessionId: input.sessionId }),
+        ...(input.toolUseId === null ? {} : { toolUseId: input.toolUseId }),
+        ...(input.cwd.length === 0 ? {} : { cwd: input.cwd }),
+        ...(provenance === null ? {} : { harness: provenance }),
+    }, actor, {}, 
+    // APRV-294: the window this verdict was decided under, and the read it was
+    // decided on. The append uses both, so a window that ended in between is
+    // reported as the thing that happened rather than as "no window is open".
+    {
+        openedSeq: window.seq,
+        ...(decidedOn === null ? {} : { read: decidedOn }),
+    });
+    if (!recorded.ok) {
+        // Invariant 8: the record lands before the allow, so a refusal here is a
+        // deny even though a window is open. `append-failed` reaches the caller
+        // through the family reserved for a code the writer produced, and so does
+        // `gate-window-closed` (APRV-294), which says the window stood when this
+        // process classified the command and does not stand now.
+        return deny(streams, `hook-gate-refused:${recorded.code}`, `${recorded.message} A window being open does not let a call run unrecorded: the record is what makes the bypass reviewable, so nothing runs without it.`, adapter.kind);
+    }
+    streams.err(bypassBanner(window, classes, recorded.record.seq));
+    const notes = [...described.notes, ...(policyNote === null ? [] : [policyNote])];
+    return allow(streams, `gate-open: ${classes.join(", ")} bypassed by the window opened at seq ${String(window.seq)} by ${window.openedBy} (expires ${window.expiresAt}); recorded as gate.bypassed seq ${String(recorded.record.seq)}${notes.length === 0 ? "" : ` (${notes.join("; ")})`}`, adapter.kind);
+}
+function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
+    const parsed = parseFlags(argv, {
+        ...COMMON_FLAGS,
+        ...POLICY_FLAGS,
+        "--log": "string",
+        "--as": "string",
+        "--timeout": "string",
+        "--interval": "string",
+        "--retry-grace": "string",
+    });
+    if (!parsed.ok)
+        return usageError(streams, parsed.message);
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${HOOK_HELP}\n`);
+        return EXIT_OK;
+    }
+    const extra = parsed.positionals[0];
+    if (extra !== undefined) {
+        return usageError(streams, `unexpected argument ${JSON.stringify(extra)}`);
+    }
+    const asFlag = stringFlag(parsed.flags, "--as");
+    const actor = asFlag ?? adapter.defaultActor;
+    if (!PRINCIPAL_ACTOR.test(actor)) {
+        return usageError(streams, `--as expects agent:<id> or human:<id>, got ${JSON.stringify(asFlag)}`);
+    }
+    const timeoutText = stringFlag(parsed.flags, "--timeout") ?? DEFAULT_TIMEOUT;
+    const timeoutMs = parseDuration(timeoutText);
+    if (timeoutMs === null) {
+        return usageError(streams, `--timeout expects a duration like 30s, 9m, got ${JSON.stringify(timeoutText)}`);
+    }
+    const intervalText = stringFlag(parsed.flags, "--interval");
+    const intervalMs = intervalText === null ? DEFAULT_INTERVAL_MS : parseDuration(intervalText);
+    if (intervalMs === null) {
+        return usageError(streams, `--interval expects a duration like 500ms, 2s, got ${JSON.stringify(intervalText)}`);
+    }
+    // APRV-287. How long the question outlives the wait, for the retry that
+    // adopts it. The duration grammar has no zero, so the shortest window is
+    // `1ms`, which withdraws as the wait expires.
+    const graceText = stringFlag(parsed.flags, "--retry-grace");
+    const graceMs = graceText === null ? HOOK_RETRY_GRACE_MS : parseDuration(graceText);
+    if (graceMs === null) {
+        return usageError(streams, `--retry-grace expects a duration like 5m, 30s, 1ms, got ${JSON.stringify(graceText)}`);
+    }
+    const parsedInput = parseHookInput(readStdin());
+    if (!parsedInput.ok)
+        return deny(streams, "hook-io", parsedInput.detail, adapter.kind);
+    const input = parsedInput.input;
+    // APRV-145: WHICH EVENT THIS IS, read first and read at all. One command is
+    // registered for two events, and they do opposite things — one answers before
+    // the tool runs, the other records how it went — so the dispatch is the first
+    // decision the verb makes.
+    //
+    // Anything that is not a post-execution event takes the pre-execution path,
+    // including an event carrying no name at all. That is the strict direction: a
+    // harness whose event this runtime does not recognize is a harness about to
+    // run a command, and treating an unknown name as a no-op would be an ungated
+    // one.
+    if (input.hookEventName !== null && POST_TOOL_EVENTS.includes(input.hookEventName)) {
+        // APRV-303. `commandHarnessHook`'s catch turns a throw into a DENY, which is
+        // the right answer for a call that has not run yet and exactly the wrong one
+        // here: it would print a verdict object about a tool call the harness has
+        // already finished, and the reason the counterpart did not land would be
+        // dressed as a permission decision. A throw on this path is `post-tool-io`,
+        // on stderr, at the exit code that makes the line visible.
+        try {
+            return runPostToolUse(parsed.flags, streams, cwd, input, actor, adapter);
+        }
+        catch (cause) {
+            return report(streams, "post-tool-io", `the counterpart failed: ${cause instanceof Error ? cause.message : String(cause)}; nothing was appended, so the start this event would have closed is still open`);
+        }
+    }
+    if (input.toolName !== adapter.shellTool && !adapter.fileTools.includes(input.toolName)) {
+        return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind);
+    }
+    // APRV-188. From here on this process may resume a verified read behind the
+    // snapshot the daemon published, instead of walking the chain from genesis:
+    // the one thing a fresh process per gated tool call cannot amortize, and the
+    // only term in a hook's cost that grows with the log. Turned on HERE rather
+    // than at the CLI's entry point, so it covers exactly the gated path and no
+    // other verb — `approval log verify` and every audit read stay cold.
+    //
+    // It changes what a read COSTS and nothing about what a read PROVES: the
+    // prefix is admitted only against a SHA-256 this process computes over the
+    // bytes it read itself, the head and the line count are re-derived from its
+    // own parse, and the appended tail is walked in full. A snapshot that is
+    // absent, stale, foreign, or wrong in any of those is ignored, and the walk
+    // happens exactly as it does today. See `core/verified-snapshot.ts`.
+    useVerifiedSnapshots(true);
+    const { logPath, root, options } = hookScope(parsed.flags, cwd);
+    // APRV-214, amended SPEC.md §5.2: the open window, looked up HERE — after the
+    // scope is resolved and before the policy is loaded — because the whole point
+    // of it is to be reachable when the things below are broken. A window opened
+    // by a human puts every gated tool call through `runBypass` instead, so an
+    // unparseable policy, a drifted attestation, a loop floor, a dark channel and
+    // a hung daemon are all bypassed.
+    //
+    // The lookup is SELF-GATING, which is what makes placing it this early safe:
+    // it reads the same verified log every enforcement path reads, and an absent,
+    // torn or unverifiable log yields no window at all. The hook then falls
+    // through to the path it has always taken and refuses there, in the same
+    // words. The window suspends the POLICY; it never suspends the log.
+    const looked = lookupWindow(logPath);
+    if (looked.window !== null) {
+        return runBypass(streams, input, adapter, cwd, logPath, parsed.flags, actor, looked.window, 
+        // APRV-294. The records this window was derived from travel with it: the
+        // bypass record is appended against the head they ended at, so the
+        // verdict and the record are one read of the log.
+        looked.records === null ? null : { records: looked.records, head: looked.head });
+    }
+    // The policy is read BEFORE the command is classified (APRV-107): the
+    // protected-path set is built-ins plus `policy.protected_paths`, so what
+    // counts as a protected path is a policy question and the classifier cannot be
+    // asked it without the answer in hand.
+    //
+    // An unloadable policy resolves everything to manual, and a manual request
+    // needs a log this hook may not be pointed at. Fail closed and say so, rather
+    // than opening a request nobody configured a channel for.
+    const load = loadPolicy(options.policy?.file === undefined
+        ? { dir: options.policy?.dir ?? cwd }
+        : { file: options.policy.file });
+    if (!load.ok) {
+        return deny(streams, "hook-policy-unavailable", `${load.code}: ${load.message}; every class resolves to manual and the hook cannot verify a decision`, adapter.kind);
+    }
+    const protectedPaths = load.policy.protected_paths ?? [];
+    // What is being asked for, as one or more classes. One description site for
+    // both paths since APRV-214 (see `describeToolCall`): the open window
+    // classifies exactly as the closed one does, and a second copy of this would
+    // be a second answer to "what is this command".
+    const described = describeToolCall(input, adapter, protectedPaths, cwd);
+    if (described.kind === "deny") {
+        return deny(streams, described.code, described.detail, adapter.kind);
+    }
+    if (described.kind === "allow")
+        return allow(streams, described.reason, adapter.kind);
+    const { classes, payload, headline } = described;
+    /** What the history-rewrite refinement did, for the decision reason. */
+    const notes = [...described.notes];
+    if (classes.length === 0) {
+        return allow(streams, "the approval CLI is the gate itself and is not gated by it", adapter.kind);
+    }
+    // Every path from here needs the log, the fast paths included (APRV-139):
+    // attestation and loop-escalation are facts about the log, so the
+    // log-unreachable deny now sits above the autonomous verdict rather than
+    // below it. A hook that could not reach the log used to allow whatever the
+    // on-disk policy called autonomous; it now denies, which is the same answer
+    // it already gave every other class.
+    if (!existsSync(logPath) && !existsSync(dirname(logPath))) {
+        return deny(streams, "hook-log-unreachable", `no log at ${logPath}; the hook writes to an existing log and never creates one. Run \`approval init\` (then \`approval policy attest\`) in ${root}, or pass --log <path> to point the hook at the log that already exists`, adapter.kind);
+    }
+    // Minted once, here, and carried into `gateAndWait`: the loop-escalation
+    // check below and any registration that follows must name the same task.
+    const task = `hook:${input.sessionId}:${input.toolUseId ?? randomBytes(8).toString("hex")}`;
+    const run = {
+        logPath,
+        options,
+        actor,
+        timeoutMs,
+        intervalMs,
+        graceMs,
+        ttlMs: load.durations.approvalTtlMs,
+        harness: adapter.kind,
+        originApp: adapter.originApp,
+        eventVersion: input.harnessVersion,
+        // Off the policy this function already loaded and validated, so the names
+        // printed are the names a channel process would serve (APRV-281). Sorted
+        // for a stable line; `Object.keys` order is the file's, and a line that
+        // changed when an operator reordered their policy would read as a change of
+        // state.
+        channels: Object.keys(load.policy.channels ?? {}).sort(),
+    };
+    const autonomies = classes.map((cls) => resolvePolicy(load, cls).autonomy);
+    // APRV-185, amended SPEC.md §5.2, and the first verdict this function reaches
+    // once the classes have autonomies. A command touching a class the policy
+    // reserves to human hands is denied outright: no request is opened, no task is
+    // registered, nothing is appended, and no human is asked — because the policy
+    // has already answered, and there is no decision anyone could make that would
+    // let this process run the command.
+    //
+    // Above the loop floor and the unattended guard deliberately. Those two route
+    // a command TO a human's gate, and this class has no gate to be routed to; a
+    // floor applied first would open a request nobody may grant. A command whose
+    // classes are mixed is denied on the strength of the one human-only class, per
+    // the classifier's existing rule that the whole command is answered by the
+    // strictest thing in it.
+    const reserved = classes.find((_cls, index) => autonomies[index] === "human-only");
+    if (reserved !== undefined) {
+        return deny(streams, "hook-class-human-only", `${humanOnlyRefusal(reserved, "this command may not run under an agent")} The gate's own code for this fact is \`class-human-only\`.`, adapter.kind);
+    }
+    // APRV-193, and BELOW the human-only deny for the same reason that one sits
+    // above the floor: a class no agent may run is answered before a question
+    // about which room it would run in. Above everything that appends, so a
+    // refused command leaves the log exactly as it found it.
+    const unsandboxed = sandboxRequirement(described.segments, autonomies);
+    if (unsandboxed !== null) {
+        return deny(streams, "hook-sandbox-required", unsandboxed, adapter.kind);
+    }
+    // APRV-145, amended SPEC.md §10.2: loop safety on a surface that mints a
+    // fresh task id per tool call. The floor is applied AFTER class resolution and
+    // never inside it, exactly as §7's irreversibility floor is: `resolve` is pure
+    // over policy text, and a failure streak is a projection over the log.
+    //
+    // The remedy is a floor and not a deny. Escalation escalates TO manual (§10.2,
+    // and `core/loop.ts`'s own header), and the only thing that clears a streak is
+    // an execution that completes — so a deny would leave an escalated session
+    // with no way back, and a class the policy calls autonomous has no manual
+    // sibling to fall back on. Every SIDE-EFFECTING class that would otherwise
+    // have proceeded is routed to the human gate for this invocation (APRV-297
+    // narrowed it to those); a class that already resolves manual is untouched,
+    // because it was already going there.
+    const floored = harnessFloor(logPath, task, actor, looked.records);
+    if (!floored.ok)
+        return deny(streams, "hook-io", floored.detail, adapter.kind);
+    /**
+     * The streak the log shows, before the read carve-out (APRV-297).
+     *
+     * Kept separate from the floor that is APPLIED because the verdict has to be
+     * able to say "a floor is standing and it was not applied here". Collapsing
+     * the two would leave an agent reading an ordinary autonomous allow with no
+     * way to tell that the session it is in is three failed writes deep.
+     */
+    const tripped = floored.floor;
+    /**
+     * Is every class of this command a read? (APRV-297, amended SPEC.md §10.2.)
+     *
+     * The predicate is `core/loop.ts`'s own, the same one that decides what
+     * ACCRUES, so what the floor counts and what it routes cannot come apart. A
+     * class this build has never heard of is side-effecting by construction, so an
+     * unknown class is routed exactly as it is counted.
+     */
+    const readsOnly = classes.every((cls) => !isSideEffectingClass(cls));
+    /**
+     * The floor as this invocation applies it: `null` for a command that only
+     * looks, whatever the streak says.
+     *
+     * A read cannot cause the harm the floor bounds. The floor exists to stop an
+     * agent retrying a side effect that keeps failing, so routing a `grep` to a
+     * phone buys no safety and spends the two things the floor is supposed to be
+     * conserving: a human's attention, and the session's ability to find out what
+     * went wrong. On 2026-09-06/07 a tripped floor sent every read to the gate and
+     * a session that could not get an answer could not even search the repository.
+     */
+    const floor = readsOnly ? null : tripped;
+    if (tripped !== null && floor === null) {
+        notes.push(`loop-escalated (amended SPEC.md §10.2) NOT APPLIED to this call: ${tripped.scope} ${tripped.key} has ${String(tripped.consecutiveFailures)} consecutive failed side-effecting harness tool calls, and every class of this command is a read (${classes.join(", ")}). Escalation raises scrutiny on side effects only, so this command is answered by the policy; the floor still routes the session's side-effecting calls to a human. ${loopClearance(tripped.scope, tripped.key)}`);
+    }
+    if (floor !== null) {
+        // The decision trace: the verdict this invocation prints says that a floor
+        // rather than the matched rule decided it, and names the scope and the
+        // count that tripped, the way `core/execute.ts` names the irreversibility
+        // floor beside a resolution's provenance.
+        notes.push(`loop-escalated (amended SPEC.md §10.2): ${floor.scope} ${floor.key} has ${String(floor.consecutiveFailures)} consecutive failed side-effecting harness tool calls, so every class of this command is routed to a human for this invocation regardless of policy`);
+    }
+    /**
+     * Appended to every verdict this invocation prints: the history-rewrite
+     * refinement's own words, and the loop floor's when one applied.
+     */
+    const note = notes.length === 0 ? "" : ` (${notes.join("; ")})`;
+    // APRV-303, and the last thing that can answer without touching the log: an
+    // ordinary workspace edit, which the policy allows on its own merits and which
+    // is a question only while a floor stands.
+    //
+    // The order is the whole fix. Until APRV-303 this allow was printed from
+    // `describeToolCall`'s own branch, several hundred lines above the floor
+    // lookup, so a session whose Bash calls were all being routed to a human went
+    // on editing files unrouted and uncounted. Now the same allow is printed, in
+    // the same words, from BELOW the floor: the fast path is as fast as it was,
+    // and the floored path routes an Edit exactly as it routes an `echo >`,
+    // because both are `files.write.workspace` and one predicate decides.
+    if (described.passthrough !== undefined && floor === null) {
+        return allow(streams, `${described.passthrough}${note}`, adapter.kind);
+    }
+    /** No class here needs a human, so nothing downstream will ask for one. */
+    const unattended = floor === null && autonomies.every((autonomy) => autonomy !== "manual");
+    if (unattended) {
+        const refused = unattendedGuard(logPath, load.source.path, task, looked.records);
+        if (refused !== null)
+            return deny(streams, refused.code, refused.detail, adapter.kind);
+    }
+    if (floor === null && autonomies.every((autonomy) => autonomy === "autonomous")) {
+        // No approval lifecycle: an autonomous action has none (amended SPEC.md
+        // §6.3), so nothing is requested, decided or granted here. What IS appended
+        // since APRV-141 is the execution record itself — the moment the policy
+        // authorized this command — because a budget the busiest path does not
+        // charge is not a budget. See `recordUnattended`.
+        const charged = recordUnattended(run, task, classes, payloadHash(payload));
+        if (charged !== null) {
+            return deny(streams, `hook-gate-refused:${charged.code}`, charged.message, adapter.kind);
+        }
+        return allow(streams, `autonomous: ${classes.join(", ")}${note}`, adapter.kind);
+    }
+    // Past here the hook appends. It writes to a log that already exists and
+    // creates none: a log the hook scaffolded where it happened to be standing
+    // would be a second chain, forked from the real one's tail, and hash chains
+    // do not survive a merge. An initialized-but-empty `.approval/log/` counts as
+    // reachable — an audit trail that has recorded nothing is an empty log, not a
+    // missing one (see `preflightLog`) — and `register` appends the first line.
+    return gateAndWait(streams, run, classes, payload, headline, task, note, floor);
+}
+function commandHarnessHook(argv, streams, cwd, readStdin, adapter) {
+    try {
+        return runHarnessHook(argv, streams, cwd, readStdin, adapter);
+    }
+    catch (cause) {
+        // A hook that throws is a hook the harness treats as a non-blocking error,
+        // which would let the command through. Every unexpected failure becomes an
+        // ordinary deny instead. Cursor additionally needs failClosed on the
+        // hooks.json entry so a crash of this process still blocks.
+        return deny(streams, "hook-io", `the hook failed: ${cause instanceof Error ? cause.message : String(cause)}`, adapter.kind);
+    }
+}
+// ===========================================================================
+// Dispatch
+// ===========================================================================
+/** Read the whole of stdin, synchronously. */
+function defaultStdin() {
+    return readFileSync(0, "utf8");
+}
+export function commandHook(argv, streams, cwd, readStdin = defaultStdin) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    if (sub === undefined) {
+        return usageError(streams, "missing subcommand for `approval hook`");
+    }
+    if (sub === "--help" || sub === "-h" || sub === "help") {
+        streams.out(`${HOOK_HELP}\n`);
+        return EXIT_OK;
+    }
+    switch (sub) {
+        case "claude-code":
+            return commandHarnessHook(rest, streams, cwd, readStdin, CLAUDE_ADAPTER);
+        case "cursor":
+            return commandHarnessHook(rest, streams, cwd, readStdin, CURSOR_ADAPTER);
+        case "classify":
+            return commandClassify(rest, streams, cwd);
+        default:
+            return usageError(streams, `unknown subcommand ${JSON.stringify(sub)} for \`approval hook\``);
+    }
+}
+//# sourceMappingURL=hook.js.map