approval-md 0.2.0 → 0.4.0

package/dist/src/cli/hook.js

@@ -72,32 +72,33 @@
  * 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 { existsSync, readdirSync, readFileSync, realpathSync, statSync, writeSync } 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 { classifyCommand, commandSegmentShapes, commandSegmentWords, CODE_EXECUTING_RULES, CONTRIBUTOR_SUFFIX, GATE_SELF_CLASS, isCredentialPath, protectedPathClass, } from "../core/command-class.js";
+import { consumeHarnessGrant, findHarnessCarry, finishHarnessExecution, isProposalTask, 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 { harnessProvenance, isHarnessKind, } from "../core/harness-version.js";
+import { abandonedAfterMs, HARNESS_CAP_MARGIN_MS, harnessCapFitsMargin, harnessCappedTtlMs, 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 { classifyApplyPatch, parseApplyPatch } from "../core/apply-patch.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 { READ_OUT_OF_SCOPE_CLASS, effectiveReadRoots, isInReadScope, readTargetsOf, renderReadRoots, } from "../core/read-scope.js";
+import { harnessLaunchNeedsRule, harnessLaunchUnruledRefusal, humanOnlyRefusal, resolve as resolvePolicy, } from "../core/policy-match.js";
+import { payloadOf, readVerifiedRecords, requestExpiresAt, 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 { HOOK_GROK_HELP, HOOK_HELP, HOOK_HERMES_HELP, HOOK_MUSE_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";
-import { checkCodexHookInput, codexBinding, CODEX_POST_TOOL_EVENT, readCodexReportedOutcome, } from "./hook-codex.js";
+import { checkCodexHookInput, codexArgvDisagrees, codexBinding, CODEX_POST_TOOL_EVENT, readCodexReportedOutcome, } from "./hook-codex.js";
 /** Identity accepted for the proposing side: a person or an agent. */
 const PRINCIPAL_ACTOR = /^(human|agent):.+/u;
 /**
@@ -110,6 +111,22 @@ const PRINCIPAL_ACTOR = /^(human|agent):.+/u;
 const DEFAULT_TIMEOUT = HOOK_DEFAULT_WAIT;
 /** Poll interval for the decision wait. */
 const DEFAULT_INTERVAL_MS = 1_000;
+/**
+ * How many CONSECUTIVE torn-tail reads the decision wait reads past before it
+ * treats the log as unreadable (APRV-427 review).
+ *
+ * The poll reads the log while other writers append to it: the daemon beside
+ * a CLI hook, and every other hook call beside one run by `approval serve`. An
+ * append is one write on an O_APPEND handle, but a reader on a filesystem that
+ * grows a file a page at a time can see the front of a line before its end, and
+ * the verified read calls that a torn tail. It is a moment in someone else's
+ * write, and the next tick reads the whole line. Treating it as terminal
+ * withdrew a live question and denied `hook-io` because a DIFFERENT call was
+ * mid-append. So a torn read is read again next tick, like a view that lags;
+ * only a tail that stays torn for this many ticks in a row (a crashed write,
+ * which nobody is going to finish) takes the old withdraw-and-deny path.
+ */
+export const TORN_TAIL_RETRIES = 5;
 /**
  * How much of the command line goes in the (claimed) summary field.
  *
@@ -151,6 +168,29 @@ export const HOOK_DENY_CODES = [
      * rejection: nobody decided anything, so there is nothing to ask again.
      */
     "hook-class-human-only",
+    /**
+     * A `harness.launch.*` class that no rule of this policy names (APRV-354).
+     *
+     * SPEC.md §7 says the family is never inferred autonomous; this is the
+     * stronger reading the family needs, which is that it is never inferred at
+     * all. A launch resolves only under a rule an operator wrote, and a policy
+     * that names neither `harness.launch.*` nor the specific member refuses.
+     *
+     * It exists because of the window the softer reading opens. Before the family
+     * existed, `codex …` and `muse …` were `hook-unclassified`: refused outright.
+     * Letting the new class fall to `defaults.autonomy` would have made every
+     * harness launch grantable by one approval in every project whose defaults
+     * are manual, the moment they upgraded — a capability arriving by upgrade
+     * rather than by decision. What that approval would cover is a whole second
+     * agent whose own actions this gate never sees.
+     *
+     * Distinct from `hook-unclassified`, which says the CLASSIFIER has nothing to
+     * say about the command; here the classifier was clear and the POLICY is
+     * silent. Distinct from `hook-class-human-only`, which is a policy that has
+     * spoken and reserved the class: the repair there is for a person to run the
+     * command, and the repair here is to write a line.
+     */
+    "hook-harness-launch-unruled",
     /** A construct whose effect cannot be read off the text (`bash -c`, `eval`). */
     "hook-opaque",
     /** The command line could not be tokenized at all. */
@@ -175,8 +215,36 @@ export const HOOK_DENY_CODES = [
      * directory, once. Past the grace the hook withdraws it (reason `timeout`),
      * because a question nothing will adopt is a message on a phone that decides
      * nothing.
+     *
+     * **Who withdraws, stated because the deny text used to imply a scheduler
+     * that does not exist (APRV-410).** This process is over when it denies, so
+     * the withdrawal is made by the NEXT gated tool call this actor makes, from
+     * the sweep at the top of every gated invocation. It cannot be anyone else: a
+     * withdrawal is the requester's own (APRV-106 rule 1, `not-requester`), the
+     * gate refuses a `system:` withdrawal outright, and the event schema binds
+     * the one `system:` withdrawal that exists to `policy-drift` and to nothing
+     * else (APRV-235). So a session that denies here and then makes no further
+     * gated call leaves the question pending until the TTL, and a decision on it
+     * lands as an ordinary grant. What stops that grant authorizing anything is
+     * the other half of APRV-410: a retry past the grace does not carry it
+     * (`findHarnessCarry`), so it asks again.
      */
     "hook-timeout",
+    /**
+     * The harness ceiling this hook was told it runs under leaves no window a
+     * human could answer in (APRV-423).
+     *
+     * `--harness-cap` (or the harness's own documented maximum) at or below
+     * `HARNESS_CAP_MARGIN_MS` means the question would lapse at the instant it
+     * was asked: the request must end a margin before the harness kills the
+     * process that opened it, and there is no room left for the asking. Nothing
+     * is registered, nothing is requested and nobody's phone lights up. The
+     * repair is a configuration change — raise the harness entry's timeout, or
+     * state the real one — and it is a refusal rather than a silent widening
+     * because a hook that quietly ignored its own ceiling would be back to
+     * recording grants on calls nobody holds.
+     */
+    "hook-harness-cap-too-short",
     /** The gate refused intake; the gate's own code follows a colon. */
     "hook-gate-refused",
     /**
@@ -219,6 +287,72 @@ export const HOOK_DENY_CODES = [
      * merges do not reconcile hash chains (APRV-101).
      */
     "hook-log-unreachable",
+    /**
+     * The harness does not tell this hook where the call will run, so no verdict
+     * over the visible bytes can bind the action (APRV-311, native evidence in
+     * APRV-310 v6/v7).
+     *
+     * Native Codex 0.152.1 honours a per-call Bash working directory that appears
+     * in no field of the event: `tool_input` carries `command` alone, and the
+     * event cwd and the hook process cwd both stay at the session root. A
+     * decision over `{command, session root}` would therefore authorize different
+     * bytes from the `{command, effective directory}` the harness executes, and a
+     * relative path in an approved command can name a protected organ in a
+     * directory the classifier never saw.
+     *
+     * Distinct from `hook-io`, which this used to borrow, and the distinction is
+     * the repair. `hook-io` says THIS event was malformed and a well-formed one
+     * would be answered; this says every event of this shape is refused on this
+     * harness version, and the fix is a harness contract that exposes the
+     * effective execution directory, not a retry, a policy edit, or an open
+     * window. Nothing appends on this path and no gate lifecycle opens.
+     */
+    "hook-unsupported-execution-context",
+    /**
+     * The session names a Contributor-tier model, so every tool call is refused
+     * (APRV-350).
+     *
+     * Meta sells a Contributor variant of the Muse Spark family that "trades a
+     * lower price for permission to train on your prompts and completions". A
+     * session on one discloses every byte it reads, so the refusal is above the
+     * policy: no class resolution and no grant widens it, and an absent or
+     * unrecognised `model` is refused for the same reason an unparseable event is.
+     *
+     * Distinct from `hook-class-human-only`, which says a HUMAN must do this
+     * action; this says nothing may do it in this session, and the repair is to
+     * change the model in Muse's picker rather than to ask anybody. Distinct from
+     * `hook-io` because the event was perfectly well formed.
+     *
+     * What it cannot do is stated wherever it is documented: it stops tool calls,
+     * and it cannot recall a prompt the model has already been sent.
+     */
+    "hook-muse-contributor-model",
+    /**
+     * A Hermes Agent `execute_code` call, refused before anything else looks at
+     * it (APRV-398).
+     *
+     * The tool takes a `code` string and runs it in-process. There is no path, no
+     * argv and no working directory: nothing the classifier reads exists in the
+     * call, so no class can be resolved and no payload can bind what will happen.
+     * A verdict over `{code}` would authorize a program this runtime never
+     * parsed, which is the same hole `hook-opaque` closes for `bash -c` and the
+     * same one `hook-unsupported-execution-context` closes for a command whose
+     * directory is invisible. SPEC.md §11.1 says ambiguity resolves to the
+     * stricter path, and the strictest honest answer to "may I run this arbitrary
+     * program" is no.
+     *
+     * Distinct from `hook-opaque`, and the distinction is the repair. That one
+     * says a command line carried a construct the classifier could not read, and
+     * the fix is to write the command differently. This one says the TOOL has no
+     * readable surface at all on this harness, so there is no spelling of an
+     * `execute_code` call that would be answered differently: the repair is to do
+     * the work through the shell tool, where the words are visible and the
+     * classifier can price them, or through `approval run` with a granted token.
+     *
+     * Distinct from `hook-unclassified`, which says the classifier had nothing to
+     * say about bytes it could see. Here there are no bytes to see.
+     */
+    "hook-hermes-execute-code-unbound",
     /** Malformed hook input, or a log/filesystem fact that stopped the check. */
     "hook-io",
 ];
@@ -267,7 +401,7 @@ const primaryRoot = resolvePrimaryRoot;
  * (`--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) {
+export function hookScope(flags, cwd) {
     const policyFlag = stringFlag(flags, "--policy");
     const logFlag = stringFlag(flags, "--log");
     const dirFlag = stringFlag(flags, "--dir");
@@ -278,12 +412,46 @@ function hookScope(flags, cwd) {
     const logPath = logFlag === null ? join(root, DEFAULT_LOG_PATH) : absolute(logFlag, cwd);
     return { logPath, root, options };
 }
+/**
+ * The GATE ROOT: the directory holding the policy file that was actually read
+ * (APRV-347).
+ *
+ * This is the anchor of the read scope, and it is deliberately the loaded
+ * policy's own directory rather than the hook's cwd or the harness's `cwd`
+ * field. A muse session started in `~/dev/muse` with its own `APPROVAL.md` gets
+ * `~/dev/muse`, and every sibling under `~/dev` is outside the scope with no
+ * extra grammar anywhere. A policy that did not load falls back to the scope
+ * root, which is the same directory the loader was pointed at.
+ */
+function policyRootOf(load, fallback) {
+    return load.ok ? dirname(load.source.path) : fallback;
+}
+/**
+ * The ceiling a harness puts on its hook process, in milliseconds, or `null`
+ * (APRV-423): the operator's stated `--harness-cap` clamped to the adapter's
+ * contractual maximum, or, with nothing stated, the adapter's documented
+ * default, falling back to that maximum.
+ *
+ * Exported so `approval serve` computes the same number the hook will before
+ * it hands the call to a thread (APRV-427 review): the budget a queued call
+ * has left is this less the time it has waited.
+ */
+export function effectiveHarnessCapMs(adapter, statedCapMs) {
+    const ceilingMs = adapter.capCeilingMs ?? null;
+    if (statedCapMs === null)
+        return adapter.capDefaultMs ?? ceilingMs;
+    return ceilingMs === null ? statedCapMs : Math.min(statedCapMs, ceilingMs);
+}
 const CLAUDE_ADAPTER = {
     kind: "claude-code",
     originApp: "claude-code-hook",
     defaultActor: "agent:claude-code",
     shellTool: "Bash",
     fileTools: ["Edit", "Write", "MultiEdit", "NotebookEdit"],
+    // Claude Code's three path-carrying readers. `Read` names the file in
+    // `file_path` (or `notebook_path`), `Glob` and `Grep` name the directory they
+    // search in `path` and default to the workspace when it is absent.
+    readTools: ["Read", "Glob", "Grep"],
 };
 const CURSOR_ADAPTER = {
     kind: "cursor",
@@ -291,6 +459,14 @@ const CURSOR_ADAPTER = {
     defaultActor: "agent:cursor",
     shellTool: "Shell",
     fileTools: ["Write", "Delete"],
+    // Cursor's own hook documentation names `Shell`, `Write` and `Delete` as the
+    // matchable tools, and no read tool among them; `Read` is the name its agent
+    // surface uses. It is listed here because an entry that Cursor never sends is
+    // INERT — an unmatched tool takes the path it took before this task — while
+    // an entry missing for a tool Cursor does send would be an unscoped read. If
+    // Cursor names it otherwise, `cat` through `Shell` is still scoped by the
+    // classifier, which is the floor. See docs/cursor-hook.md.
+    readTools: ["Read"],
 };
 const CODEX_ADAPTER = {
     kind: "codex",
@@ -298,14 +474,391 @@ const CODEX_ADAPTER = {
     defaultActor: "agent:codex",
     shellTool: "Bash",
     fileTools: ["apply_patch"],
+    // Empty, and not an oversight. The Codex native hook contract exposes exactly
+    // two tools, `Bash` and `apply_patch` (docs/codex-hook.md); it has no
+    // separate read tool to gate. Codex `Bash` is refused outright today because
+    // the contract does not expose the per-call working directory (APRV-310), so
+    // a Codex read arrives as a shell command and is scoped by the classifier or
+    // it does not arrive at all.
+    readTools: [],
     bindToolName: true,
 };
+/**
+ * Grok Build (APRV-243).
+ *
+ * Its PreToolUse hook is modelled on Claude Code's, with three differences
+ * that matter here: the envelope keys are camelCase, the verdict is
+ * `{decision, reason}` rather than the nested `hookSpecificOutput`, and a deny
+ * is EXIT 2 rather than exit 0 with a JSON body. The tool names are Claude
+ * Code's, which is what its documentation says and what the compatibility read
+ * of `.claude/settings.json` implies; `docs/grok-hook.md` records that this
+ * half is unverified until the live probe runs.
+ *
+ * The reason this adapter exists at all is a hazard rather than a feature.
+ * Grok Build states that it reads `.claude/settings.json` for compatibility.
+ * If that read fires this repository's committed claude-code entry under a
+ * Grok session, the claude-code adapter answers a deny by printing the nested
+ * Claude envelope and exiting 0, and Grok reads exit 0 as ALLOW. Every command
+ * would look gated and none would be.
+ */
+const GROK_ADAPTER = {
+    kind: "grok",
+    originApp: "grok-hook",
+    defaultActor: "agent:grok",
+    shellTool: "Bash",
+    fileTools: ["Edit", "Write", "MultiEdit", "NotebookEdit"],
+    // Claude Code's three path-carrying readers, for the same reason the file
+    // tools are Claude Code's: Grok Build's tool vocabulary follows Claude
+    // Code's, and it READS `.claude/settings.json` for compatibility, so the
+    // names a Grok session sends are the names that file matches on. The
+    // asymmetry with Cursor is deliberate — Cursor documents its own smaller set,
+    // Grok documents Claude's.
+    //
+    // Both directions of the guess are safe in the way APRV-347 makes them safe.
+    // A read tool listed here that Grok never sends is INERT: an unmatched tool
+    // takes the path it took before. A read tool Grok sends that is NOT listed
+    // would be an unscoped read, which is the direction that matters, so the
+    // wider Claude set is the fail-closed guess. And a Grok read that arrives as
+    // a shell command through `Bash` is scoped by the classifier regardless,
+    // which is the floor under all of this.
+    //
+    // UNVERIFIED, like the file-tool list beside it, and `docs/grok-hook.md`
+    // says so: the live probe of APRV-243 AC1 records the tool names an actual
+    // session sends, and both lists are corrected to match before the register
+    // entry moves from parked.
+    readTools: ["Read", "Glob", "Grep"],
+    camelCaseEnvelope: true,
+};
+/**
+ * Meta Muse Code (APRV-350).
+ *
+ * Every field here is OBSERVED, from a live run on `muse-bin-1.3.0-R3233.1`
+ * whose 139 captured envelopes are the evidence. Nothing in this entry is a
+ * guess, which is the difference between it and the Grok entry above.
+ *
+ * The envelope is snake_case, so no `camelCaseEnvelope`. It carries
+ * `hook_event_name`, `tool_name`, `tool_input`, `tool_use_id`, `session_id`,
+ * `turn_id`, `cwd`, `transcript_path`, `model`, `permission_mode` and
+ * `model_provider`; `PostToolUse` adds `tool_response`. So Muse sends BOTH
+ * facts Codex lacks: a per-call working directory and a real outcome.
+ *
+ * ## What it cannot do, and why this adapter still ships
+ *
+ * Muse FAILS OPEN. A hook that crashes, hangs past its timeout, or prints
+ * anything Muse cannot parse is a hook Muse ignores, and the tool call
+ * proceeds. Worse, an output mixing verdict dialects is itself unparseable, so
+ * the belt-and-braces answer that satisfies every harness at once satisfies
+ * this one not at all: the probe's `deny` trial printed every dialect AND
+ * exited 2, and the write completed in under 80 ms.
+ *
+ * Therefore this adapter emits EXACTLY ONE dialect and nothing else: the nested
+ * `hookSpecificOutput` form at exit 0, which the default arm of
+ * {@link decision} already produces. Three forms were measured to block
+ * (nested at exit 0; `{decision:"block"}` at exit 0; empty stdout at exit 2)
+ * and the nested one is chosen because it is the only one that carries a REASON
+ * the model is shown, so a refused agent learns why instead of retrying blind.
+ * The probe watched an agent respond to an unexplained deny by shelling out to
+ * inspect the hook's own state file, which is the behaviour a silent refusal
+ * buys. `docs/muse-hook.md` records the choice and the two rejected forms.
+ */
+const MUSE_ADAPTER = {
+    kind: "muse",
+    originApp: "muse-hook",
+    defaultActor: "agent:muse",
+    shellTool: "bash",
+    fileTools: ["write_file"],
+    // `read_file` names one path (relative to the session cwd, or absolute);
+    // `search` names an ARRAY under `paths`, and the live capture caught it
+    // reaching outside the workspace entirely — Muse applies no workspace
+    // confinement in `permission_mode: "default"`, so this is the read jail's
+    // whole reason for existing here.
+    readTools: ["read_file", "search"],
+    passThroughTools: ["submit_reminder_decision"],
+    shellCwdKey: "workdir",
+    contributorModelGuard: true,
+};
+/**
+ * Hermes Agent's event names, which are its own and not Claude Code's
+ * (APRV-398).
+ *
+ * snake_case, and the VERBS differ too: `pre_tool_call` where every other
+ * harness in this table says `PreToolUse`. That is why they are constants
+ * rather than two more entries in {@link POST_TOOL_EVENTS} — a harness whose
+ * post-event name appeared in that shared list would also accept
+ * `PostToolUse` from an event nobody sent, and the dispatch would answer a
+ * name this harness never uses.
+ */
+export const HERMES_PRE_TOOL_EVENT = "pre_tool_call";
+export const HERMES_POST_TOOL_EVENT = "post_tool_call";
+/**
+ * Hermes Agent's read tools, read off its own tool registrations (APRV-398).
+ *
+ * `read_file` names one `path` (with `offset` and `limit`). `search_files` is
+ * BOTH of the readers another harness would ship as two: its `target` enum
+ * selects `content` (a grep) or `files` (a name search), and either way the
+ * directory it works in is one `path`. So there is no `glob`, no `grep` and no
+ * `list_files` here — not because they were left out, but because this harness
+ * does not have them.
+ *
+ * NO TOOL ON THIS HARNESS TAKES A LIST OF PATHS, which is the one thing worth
+ * saying out loud: Muse's `search` names an ARRAY under `paths` and needed
+ * `firstOutOfScope` to answer a list, and `readToolGate`'s single-path arm
+ * answers everything here. A `paths` array arriving from a future release would
+ * fall to that same list handling with no change, because the gate reads both.
+ *
+ * OBSERVED (APRV-415, the live probe of APRV-398): a running session sent
+ * `read_file` with `path` and `limit`, and the tools it sent in total were
+ * `terminal`, `write_file`, `patch`, `read_file` and `execute_code`.
+ * `search_files` was not exercised by the five prompts, so it stays on this list
+ * as the registration says, in the direction APRV-347 made safe: a listed tool
+ * Hermes never sends is INERT, an unlisted tool it does send would be an
+ * unscoped read. A read arriving through `terminal` as `cat` is scoped by the
+ * classifier regardless, which is the floor under all of it.
+ */
+const HERMES_READ_TOOLS = ["read_file", "search_files"];
+/**
+ * The classes Hermes's own side-effecting tools are judged under (APRV-445,
+ * from the Agent Village DATA-234 survey of Hermes v2026.9.24).
+ *
+ * Before this table every one of these reached the not-a-gated-tool allow,
+ * because the adapter knew `terminal`, `write_file`, `patch` and the two read
+ * tools and nothing else, so a policy line for `cron.manage` or `message.send`
+ * was a line no Hermes call could ever reach. They are code, not policy: the
+ * classifier decides what a call IS and the policy decides what happens to it,
+ * so an operator prices these classes with ordinary `classes:` lines.
+ *
+ * - `cronjob_manage` (legacy alias `cronjob`): every action that changes the
+ *   schedule or runs a job is `cron.manage`; `list` is a read. A scheduled job
+ *   runs later with no `pre_tool_call` at all, so the schedule is the one place
+ *   a human can see it.
+ * - `process_manage` (legacy alias `process`): `write`, `submit`, `kill`,
+ *   `close` and `handoff` act on a running process and are `process.write`;
+ *   `list`, `poll`, `log` and `wait` are reads.
+ * - `browser_exec`, `browser_cdp` and every other `browser_*`: `browser.exec`.
+ * - `skill_manage`: `skill.manage`. `delegate_task`: `agent.delegate`.
+ *   `send_message`: `message.send` (not agent-callable at v2026.9.24; the rule
+ *   stands so the day it is, it is already gated).
+ *
+ * An action this table does not recognise on a tool it does know is judged
+ * under the tool's side-effecting class rather than allowed: a new verb on a
+ * tool that schedules or drives processes is a new way to do that, and the
+ * strict reading is the safe one.
+ */
+const HERMES_CRON_READ_ACTIONS = new Set(["list"]);
+const HERMES_PROCESS_READ_ACTIONS = new Set(["list", "poll", "log", "wait"]);
+function hermesToolRule(toolName, toolInput) {
+    const action = readString(toolInput, "action");
+    const headline = (cls) => `${toolName}${action === null ? "" : ` ${action}`} (${cls})`;
+    if (toolName === "cronjob_manage" || toolName === "cronjob") {
+        if (action !== null && HERMES_CRON_READ_ACTIONS.has(action)) {
+            return { kind: "read", reason: `${toolName} ${action} reads the schedule and changes nothing` };
+        }
+        return { kind: "gated", cls: "cron.manage", headline: headline("cron.manage") };
+    }
+    if (toolName === "process_manage" || toolName === "process") {
+        if (action !== null && HERMES_PROCESS_READ_ACTIONS.has(action)) {
+            return { kind: "read", reason: `${toolName} ${action} reads a process and changes nothing` };
+        }
+        return { kind: "gated", cls: "process.write", headline: headline("process.write") };
+    }
+    if (toolName.startsWith("browser_")) {
+        return { kind: "gated", cls: "browser.exec", headline: headline("browser.exec") };
+    }
+    if (toolName === "skill_manage") {
+        return { kind: "gated", cls: "skill.manage", headline: headline("skill.manage") };
+    }
+    if (toolName === "delegate_task") {
+        return { kind: "gated", cls: "agent.delegate", headline: headline("agent.delegate") };
+    }
+    if (toolName === "send_message") {
+        return { kind: "gated", cls: "message.send", headline: headline("message.send") };
+    }
+    return null;
+}
+/**
+ * Hermes Agent by Nous Research (APRV-398).
+ *
+ * The harness Agent Village v2 runs every resident agent on, one per tenant in
+ * a Railway sandbox, which is why this adapter exists at all. Its hook is a
+ * shell hook like every other entry in this table, configured under `hooks:` in
+ * `$HERMES_HOME/config.yaml` rather than in the repository: Hermes documents no
+ * project-local configuration directory, so the organ lives in the user home
+ * and `core/command-class.ts` matches it there.
+ *
+ * ## The dialect: exactly one form, and the form is Hermes's own
+ *
+ * Hermes's shell-hook parser accepts two block dialects, checked in this order:
+ * its own `{action:"block", message}` and a Claude-compatible
+ * `{decision:"block", reason}`. This adapter emits the NATIVE one and never
+ * both.
+ *
+ * The live probe (APRV-415) measured every dialect one at a time and then all of
+ * them at once: `{action:"block"}` at exit 2, `{action:"block"}` at exit 0,
+ * `{decision:"block"}`, a bare exit 2, and the mixed payload ALL BLOCKED. So
+ * HERMES TOLERATES A SUPERSET, which is exactly where it differs from Muse — a
+ * payload carrying several dialects there was unparseable, an unparseable hook
+ * was a failed hook, and a failed hook failed OPEN, so being more explicit made
+ * the refusal weaker (`docs/muse-hook.md`). One dialect is still what this
+ * adapter emits, and the reason is now the smaller one rather than the load-
+ * bearing one: the native form is the shape the parser tries first and the one
+ * least likely to be dropped by a release that tidies up a compatibility layer,
+ * and a verdict whose meaning does not depend on how much of it the harness
+ * understood is a verdict a reader can check. The tolerance is a fact about this
+ * release, not a licence to hedge in the next one.
+ *
+ * THE ALLOW IS `{}`, and that is not a placeholder. Hermes has no
+ * `{"action":"allow"}`: its parser returns "no directive" for an empty stdout,
+ * for `{}`, and for any JSON object naming no directive key, and no directive
+ * means the call proceeds. The probe confirmed it: the `allow-empty-object`
+ * trial CREATED its file under `fail_closed: true`. `{}` is chosen over an empty
+ * stdout because the two are distinguishable to a human reading a log and only
+ * one of them says a hook ran and decided; it is chosen over an invented
+ * `{"action":"allow"}` because that spelling is an allow only by falling through
+ * the parser's unrecognised-directive path — which the probe also measured, and
+ * which did fall through on the old build — and a verdict that works by not being
+ * understood is a verdict one release could turn into a block. The reason text
+ * rides on stderr, where Hermes reads it only as a block message at the blocking
+ * exit code, which an allow never uses.
+ *
+ * ## The first real gate since Claude Code, measured
+ *
+ * A per-entry `fail_closed: true` turns three hook failures into a BLOCK: a
+ * spawn error, a timeout, and stdout that is non-empty and not a JSON object.
+ * Grok Build and Muse Code both fail open on all three with no setting to change
+ * it, so both adapters are enforcement only while healthy.
+ *
+ * OBSERVED, 3 OF 3, on Hermes `main` at `118984d7` (APRV-415): the armed crash
+ * was refused, the armed garbage was refused, and the armed hang was refused at
+ * exactly 300s, the per-entry cap. So this adapter is a gate on a current Hermes
+ * rather than a backstop, which no adapter since Claude Code could say.
+ *
+ * THREE LIMITS RIDE WITH IT, and `docs/hermes-hook.md` states all three rather
+ * than selling the headline. The default is `false`, so an entry without the key
+ * fails open. The key does not cover a hook that exits non-zero having printed
+ * NOTHING, which is left to {@link HERMES_DENY_EXIT}'s unconditional block. And
+ * there is a VERSION FLOOR: `v0.21.3` (build `2026.9.14`) does not know the key
+ * at all and ignores it silently, with `hermes hooks list` rendering no
+ * `fail_closed` flag on either build, so the listing cannot be used to check it.
+ * {@link HERMES_FAIL_CLOSED_FLOOR} in `core/harness-version.ts` carries the floor
+ * and `approval doctor`'s harness-version row reports a build below it.
+ *
+ * ## `execute_code` has no readable surface, and may not even be hooked
+ *
+ * The tool takes a `code` string and no path, no argv and no directory, so
+ * nothing a verdict could bind exists in the call. It is refused before the
+ * event dispatch with {@link HERMES_EXECUTE_CODE_REFUSAL}.
+ *
+ * There is a second reason, and it is the stronger one. `execute_code` runs in
+ * a persistent kernel whose scripts can call Hermes's other tools IN-PROCESS.
+ * Whether those inner calls re-fire `pre_tool_call` is STILL not established and
+ * cannot be established from here: the probe refused every `execute_code` call
+ * before it ran, twice, which is the refusal working and is also the reason no
+ * inner call was ever observed. If they do not re-fire, one `execute_code` call
+ * is an unbounded bypass of this entire adapter. Refusing the tool is the only
+ * answer available to a hook that cannot see inside it, and it is the
+ * fail-closed one.
+ */
+const HERMES_ADAPTER = {
+    kind: "hermes",
+    originApp: "hermes-hook",
+    defaultActor: "agent:hermes",
+    // Two numbers, because Hermes bounds the hook twice and the shorter wins.
+    //
+    // The CEILING is 300 s, OBSERVED rather than read off a page: APRV-415's probe
+    // armed a hang and Hermes refused it at exactly 300 s, the per-entry cap. No
+    // entry can outlive it however it is written, so a stated `--harness-cap` is
+    // clamped to it.
+    //
+    // The DEFAULT is 30 s: `plugins.hook_callback_timeout`, which bounds the whole
+    // hook dispatch, fails closed on `pre_tool_call` by itself, and is what a
+    // Hermes install runs with until an operator raises it. The first pass of
+    // APRV-423 assumed the 300 s ceiling whenever the flag was absent, which on a
+    // default install asserted a T+240 s deadline for a hook Hermes kills at 30 s:
+    // APRV-410 again, with a fictional deadline. So with no flag the runtime
+    // assumes the stricter number, which does not clear the margin, and refuses
+    // `hook-harness-cap-too-short` with the repair below. An operator who has
+    // raised `hook_callback_timeout` states the smaller of it and the entry's
+    // `timeout` with `--harness-cap`, and that statement replaces the default.
+    capCeilingMs: 300_000,
+    capDefaultMs: 30_000,
+    capRepair: "On Hermes: raise `plugins.hook_callback_timeout` above the per-entry `timeout` in the harness's config, then pass `--harness-cap <the smaller of the two>` on the hook command, or start `approval serve` with `--hook-harness-cap <the smaller of the two>` for a hosted tenant (for the documented `hook_callback_timeout: 600` with `timeout: 300`, that is 300s). Without the flag this runtime assumes Hermes's 30s default callback timeout, which leaves no room for a human.",
+    // `terminal`, carrying `command` and a PER-CALL `workdir`. Hermes's contract
+    // has the field Codex's withholds (APRV-310), and the live probe found that
+    // having it is not the same as being sent it: the model passed no `workdir` at
+    // all, and the directory the command would have run in is reported nowhere
+    // else. So the field makes enforcement POSSIBLE and
+    // {@link hermesUnboundDirectory} is what makes it actual, by refusing the call
+    // that leaves the field out instead of guessing a directory for it.
+    shellTool: "terminal",
+    // `write_file` names `path` and `content`; `patch` names `path`,
+    // `old_string` and `new_string`. Both shapes are already what
+    // `fileToolGate` reads, so neither needed a new key. Both were observed on the
+    // live run, `patch` with `new_string`, `old_string` and `path` exactly.
+    fileTools: ["write_file", "patch"],
+    readTools: HERMES_READ_TOOLS,
+    shellCwdKey: "workdir",
+    toolRules: hermesToolRule,
+};
+/** The adapter's rule-table verdict for this call, or `null` (APRV-445). */
+function toolRuleOf(adapter, input) {
+    if (adapter.toolRules === undefined)
+        return null;
+    if (input.toolName === adapter.shellTool)
+        return null;
+    if (adapter.fileTools.includes(input.toolName) || adapter.readTools.includes(input.toolName)) {
+        return null;
+    }
+    return adapter.toolRules(input.toolName, input.toolInput);
+}
+/**
+ * Every harness this runtime speaks a hook protocol for, by kind (APRV-358).
+ *
+ * The table is `Record<HarnessKind, HarnessAdapter>` rather than a list of
+ * consts and a switch, and the type is the point: a kind added to
+ * `HARNESS_KINDS` with no adapter beside it fails to compile, so the two lists
+ * cannot drift by forgetting. The subcommand dispatch below reads this map, so
+ * `approval hook <kind>` is answerable for exactly the kinds named here.
+ *
+ * The kinds that are enumerated OUTSIDE this module — the schema's
+ * `payload.harness` enum, the verb registry's `hook` subcommands, the MCP
+ * exclusions, the help — are pinned set-equal to `HARNESS_KINDS` by
+ * `tests/harness-enum.test.ts`, which exists because `grok` shipped an adapter
+ * in APRV-243 and reached none of them. A Grok session's manual-class
+ * registration was refused at the write boundary for eleven days and nothing
+ * failed.
+ */
+export const HARNESS_ADAPTERS = {
+    "claude-code": CLAUDE_ADAPTER,
+    cursor: CURSOR_ADAPTER,
+    codex: CODEX_ADAPTER,
+    grok: GROK_ADAPTER,
+    muse: MUSE_ADAPTER,
+    hermes: HERMES_ADAPTER,
+};
+/**
+ * Is `name` this adapter's post-execution event?
+ *
+ * One reading of the question, so the three places that used to spell it
+ * themselves cannot come apart (APRV-398). Codex names one event, Hermes names
+ * its own snake_case pair, and everything else uses Claude Code's two; a
+ * harness whose names appeared in another harness's list would answer an event
+ * nobody sent it.
+ */
+function isPostToolEvent(adapter, name) {
+    if (name === null)
+        return false;
+    if (adapter.kind === "codex")
+        return name === CODEX_POST_TOOL_EVENT;
+    if (adapter.kind === "hermes")
+        return name === HERMES_POST_TOOL_EVENT;
+    return POST_TOOL_EVENTS.includes(name);
+}
 /**
  * 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`.
+ * `{permission, user_message, agent_message}`. Grok Build wants
+ * `{decision, reason}`. One construction site per harness, still never `ask`.
  */
 function decision(permission, reason, harness, codexCommand) {
     if (harness === "cursor") {
@@ -315,6 +868,36 @@ function decision(permission, reason, harness, codexCommand) {
             agent_message: reason,
         })}\n`;
     }
+    if (harness === "grok") {
+        return `${JSON.stringify({ decision: permission, reason })}\n`;
+    }
+    if (harness === "hermes") {
+        // APRV-398. Hermes's OWN block form and exactly one form:
+        // `{action:"block", message}`. It emits neither the Claude-compatible
+        // `{decision:"block", reason}` beside it nor any other key, and the test
+        // asserts the top-level keys precisely so a later edit cannot quietly add
+        // one — on Muse a verdict carrying an unsupported key was a FAILED hook and
+        // a failed hook failed open, which made the more explicit refusal the weaker
+        // one. APRV-415 measured Hermes on the same question and it is NOT Muse: the
+        // mixed payload blocked, so this harness tolerates a superset. One dialect is
+        // kept anyway, because the tolerance is a property of one release and a
+        // verdict whose meaning depends on how much of it the harness parsed is not a
+        // verdict a reader can check.
+        //
+        // THE ALLOW IS `{}` AND CARRIES NO REASON, which is the harness's own
+        // vocabulary rather than a shrug: Hermes has no allow directive, and a
+        // parser that finds no directive lets the call proceed. `{}` over an empty
+        // stdout because a human reading a log can tell a hook that decided from a
+        // hook that printed nothing; `{}` over an invented `{"action":"allow"}`
+        // because that would be an allow only by falling through the parser's
+        // unrecognised path, and a verdict that works by not being understood is one
+        // release away from being a block. The reason reaches stderr instead (see
+        // {@link allow}), where it is read as a block message at the blocking exit
+        // code and nowhere else.
+        return permission === "deny"
+            ? `${JSON.stringify({ action: "block", message: reason })}\n`
+            : "{}\n";
+    }
     const hookSpecificOutput = {
         hookEventName: "PreToolUse",
         permissionDecision: permission,
@@ -330,17 +913,240 @@ function allow(streams, reason, harness, codexCommand) {
     if (harness === "codex" && codexCommand === undefined) {
         return deny(streams, "hook-io", "the Codex allow lost its exact bound tool_input.command", harness);
     }
+    // APRV-398. Hermes's allow is `{}` and has nowhere to put a reason, so the
+    // reason goes to stderr rather than being dropped: it names the classes the
+    // verdict authorized and carries the loop floor's own words when one stood,
+    // which is the line an operator reads back off a session. Hermes reads stderr
+    // only as a block message at the blocking exit code, and an allow never uses
+    // that exit code, so this cannot become part of a verdict.
+    if (harness === "hermes")
+        streams.err(`approval hook hermes: allow — ${reason}\n`);
     streams.out(decision("allow", reason, harness, codexCommand));
     return EXIT_OK;
 }
+/**
+ * The exit code a DENY carries.
+ *
+ * Claude Code, Cursor and Codex read the verdict out of stdout and treat a
+ * non-zero exit as a broken hook, so a deny there exits 0 with a JSON body.
+ * Grok Build reads exit 2 as the deny (APRV-243), and reads exit 0 as ALLOW
+ * whatever stdout said. Printing the body AND exiting 2 satisfies both halves
+ * of its documented contract and leaves the reason where a person can read it.
+ */
+const GROK_DENY_EXIT = 2;
+/**
+ * The exit code a HERMES deny carries, and why it IS 2 (APRV-398).
+ *
+ * This is the one place the Muse reasoning does not carry over, and the
+ * difference is in Hermes's own code rather than in a preference. Hermes defines
+ * a blocking exit code, applies it to `pre_tool_call` and to no other event, and
+ * treats it as UNCONDITIONAL: the call is blocked whatever stdout said, and the
+ * block message is taken from the stdout directive first, from stderr second,
+ * and from a default third. So the body and the exit code are not two accounts
+ * of one answer that the harness has to reconcile — the harness states the
+ * precedence itself, and the two agree by its own rule.
+ *
+ * That makes 2 strictly stronger than 0 here, and it closes the one gap
+ * `fail_closed` leaves open. `fail_closed: true` blocks on a spawn error, a
+ * timeout, and stdout that is non-empty and not a JSON object; it does NOT block
+ * a hook that exits non-zero having printed nothing, because its condition
+ * requires a non-empty stdout. Exiting 2 means every refusal this adapter
+ * reaches blocks on the exit code alone, including the ones where the body never
+ * made it out.
+ *
+ * Grok's 2 and this 2 are therefore the same number for opposite reasons, and it
+ * is worth not conflating them: there, exit 2 is the ONLY signal Grok reads and
+ * the body is decoration. Here the body is the message and the exit code is the
+ * floor under it.
+ */
+const HERMES_DENY_EXIT = 2;
 function deny(streams, code, detail, harness) {
     streams.out(decision("deny", `${code}: ${detail}`, harness));
+    if (harness === "grok")
+        return GROK_DENY_EXIT;
+    if (harness === "hermes")
+        return HERMES_DENY_EXIT;
     return EXIT_OK;
 }
+/**
+ * The block directive a harness reads, as bytes, for a refusal raised OUTSIDE
+ * the hook (APRV-421).
+ *
+ * `approval serve` can refuse a hook request before `commandHook` is reached
+ * at all: an oversized body, a credential at the wrong door, a method it does
+ * not answer. Each of those is a refusal by the transport, and a transport
+ * refusal a harness reads as "no verdict" is a harness that runs the command.
+ * So the refusal has to be spoken in the harness's own dialect, and the only
+ * correct source of that dialect is the function that prints it here.
+ *
+ * It renders through {@link deny} for that reason: one construction site per
+ * harness, still never `ask`. The exit code returned is the one the verb would
+ * have carried; a caller may impose a stricter one, and the transport does.
+ */
+export function harnessBlockDirective(code, detail, harness) {
+    const out = [];
+    const exitCode = deny({ out: (text) => out.push(text), err: () => undefined }, code, detail, harness);
+    return { stdout: out.join(""), exitCode };
+}
+/** The machine-readable code a Hermes `execute_code` call is refused with. */
+export const HERMES_EXECUTE_CODE_REFUSAL = "hook-hermes-execute-code-unbound";
+/** The tool that carries a program and no path, no argv and no directory. */
+const HERMES_EXECUTE_CODE_TOOL = "execute_code";
+/**
+ * The retry a Hermes session makes after one of these refusals, in one place.
+ *
+ * It is the whole point of refusing rather than falling back: a session that is
+ * told what to send next stays usable, and the live probe watched the model
+ * answer a block by trying the SAME effect through another tool and another
+ * directory. A refusal that did not name the repair would get that behaviour
+ * again, one tool along.
+ */
+const HERMES_ABSOLUTE_RETRY = "spell the directory in full from `/` and send the call again; the classifier then reads the same path the harness will write";
+/**
+ * A Hermes call whose effective directory this hook cannot see, as the reason it
+ * is refused, or `null` when the call binds its own directory (APRV-415).
+ *
+ * ## The fact, observed rather than reasoned
+ *
+ * The live probe of APRV-398 (Hermes `main` at `118984d7`, 60 envelopes) settled
+ * three things that together make this refusal necessary:
+ *
+ * 1. the envelope's `cwd` is the Hermes PROCESS directory (`Path.cwd()` in its
+ *    payload builder), which is not where the work happens. A session launched in
+ *    the scratch project wrote into `$HERMES_HOME/cache/scratch`, and a Telegram
+ *    gateway session's `cwd` was the USER HOME;
+ * 2. `terminal` keeps a PER-SESSION recorded working directory that a `cd` in an
+ *    earlier call moves, and no field of the event reports it. The model passed
+ *    no `workdir` at all on the probe's shell call;
+ * 3. all four file tools resolve a RELATIVE path against that same unreported
+ *    directory (`tools/file_tools_paths.py`, `_resolve_path_for_task`).
+ *
+ * So a call that does not state an absolute directory is the APRV-310 shape
+ * across every tool on this harness: the verdict would bind bytes in one
+ * directory and the harness would act in another. That is not a narrower answer
+ * this runtime may reach by guessing, and `describeToolCall`'s fallback to the
+ * event `cwd` — correct on Muse, where `cwd` IS the session root — would bind a
+ * directory that does not even contain the work here.
+ *
+ * ## Why a refusal rather than a fallback, and why it is usable
+ *
+ * SPEC.md §11.1: ambiguity resolves to the stricter path, and a self-reported
+ * field never reduces scrutiny. A relative `workdir` cannot widen anything, and
+ * on this harness it cannot be narrowed into either, because there is no
+ * trustworthy directory to fall back TO. The refusal carries
+ * `hook-unsupported-execution-context`, the same code the Codex `Bash` refusal
+ * carries, because it is the same defect — the harness did not say WHERE — and
+ * the repair differs only in being available: a Hermes session repairs it
+ * itself, in the next call, by naming an absolute path. That is why the reason
+ * names the retry rather than describing the contract.
+ *
+ * The probe also watched what a blocked model does next: it retries the same
+ * effect through another tool or another path. Refusing the shell tool alone
+ * would have moved the work into `write_file`, which is exactly why every gated
+ * tool is covered here and why an ABSENT path is refused beside a relative one.
+ * A missing `path` on this harness does not mean "the workspace" the way Claude
+ * Code's `Glob` does; it means that same unreported recorded directory.
+ */
+function hermesUnboundDirectory(input, adapter) {
+    const tool = input.toolName;
+    if (tool === adapter.shellTool) {
+        const key = adapter.shellCwdKey ?? "workdir";
+        const declared = readString(input.toolInput, key);
+        if (declared !== null && isAbsolute(declared))
+            return null;
+        return `Hermes \`${tool}\` is refused because the call ${declared === null
+            ? `states no \`${key}\``
+            : `states a relative \`${key}\` (${JSON.stringify(declared)})`}, and this harness reports the effective directory nowhere else: its \`cwd\` is the Hermes process directory, while the command runs in a per-session directory that an earlier \`cd\` moves and no field of this event carries. A verdict over the command alone would bind bytes in a directory the hook cannot see. Set \`${key}\` to an absolute path — ${HERMES_ABSOLUTE_RETRY}. No policy or open window authorizes bytes whose directory the hook cannot bind`;
+    }
+    if (!adapter.fileTools.includes(tool) && !adapter.readTools.includes(tool))
+        return null;
+    // The same keys `fileToolGate` and `readToolGate` read, in their order, plus
+    // the `paths` array neither Hermes tool sends today: a later release that
+    // added one would otherwise arrive as an unbound call that reads as bound.
+    const declared = readString(input.toolInput, "path") ??
+        readString(input.toolInput, "file_path") ??
+        readString(input.toolInput, "notebook_path");
+    const list = input.toolInput["paths"];
+    const entries = Array.isArray(list)
+        ? list.filter((entry) => typeof entry === "string" && entry.trim() !== "")
+        : [];
+    const candidates = declared === null ? entries : [declared, ...entries];
+    if (candidates.length === 0) {
+        return `Hermes \`${tool}\` is refused because the call names no path at all. On this harness an unnamed target is not the workspace: it is the per-session recorded directory that an earlier \`cd\` moves and that no field of this event carries, and a live session's was \`$HERMES_HOME/cache/scratch\` while a gateway session's was the user's home. Name the directory or file with an absolute \`path\` — ${HERMES_ABSOLUTE_RETRY}`;
+    }
+    const relative = candidates.find((candidate) => !isAbsolute(candidate));
+    if (relative === undefined)
+        return null;
+    return `Hermes \`${tool}\` is refused because the path it names is relative (${JSON.stringify(relative)}), and Hermes resolves a relative path against the per-session recorded directory that an earlier \`cd\` moves, which this event does not carry: its \`cwd\` is the Hermes process directory. The verdict and the write would name different files. Send the same call with an absolute path — ${HERMES_ABSOLUTE_RETRY}. No policy or open window authorizes a path the hook cannot place`;
+}
+/** The machine-readable code a Contributor-tier session is refused with. */
+export const MUSE_CONTRIBUTOR_REFUSAL = "hook-muse-contributor-model";
+/**
+ * Refuse every tool call on a Contributor-tier model, whatever the policy says.
+ *
+ * Meta sells two tiers of the Muse Spark family and marks the difference in the
+ * model id: a Contributor variant "trades a lower price for permission to train
+ * on your prompts and completions", against a Standard variant documented as
+ * never trained on. So a Contributor session discloses every file it reads, and
+ * a policy that would autonomously allow a read of the workspace was not
+ * written with that in mind.
+ *
+ * ## Why this is not a policy line
+ *
+ * A policy grants and withholds authority over CLASSES. This is not about the
+ * class of the action; the same `read.file` is fine on one model and a
+ * disclosure on another. Encoding it as policy would mean every operator's
+ * `APPROVAL.md` had to name Meta's tiering to be safe, and one that did not
+ * would be silently unsafe. So the adapter refuses, above the policy, and no
+ * policy can widen it. That is a strictness increase only, which is the one
+ * direction a hook may move a verdict on its own (SPEC §11.1 invariant 4).
+ *
+ * ## The self-reported field
+ *
+ * `model` is the harness's claim about itself, and SPEC §11.1 says a
+ * self-reported field never REDUCES scrutiny. This only ever raises it: the
+ * string can refuse a call, never authorize one. An absent, empty or
+ * unparseable `model` is refused too, because a session that will not say what
+ * it is running is exactly the one not to trust with a read.
+ *
+ * ## What it cannot do
+ *
+ * It stops tool calls. It cannot recall the prompt that was already sent — a
+ * hook fires after the model has seen it — and it cannot know what the harness
+ * attached as context before the first tool call. `docs/muse-hook.md` opens
+ * with this, because a guard people over-trust is worse than no guard.
+ */
+function contributorModelRefusal(model) {
+    if (model === null || model.trim() === "") {
+        return "the envelope names no model, and a session that will not say what it is running cannot be recognised as non-contributor";
+    }
+    if (model.trim().toLowerCase().includes(CONTRIBUTOR_SUFFIX.replace(/^-/u, ""))) {
+        return `${model.trim()} is a Contributor-tier model: Meta trains on this tier's prompts and completions, so every file this session reads is disclosed. Refused regardless of policy; no grant widens it.`;
+    }
+    return null;
+}
 function readString(source, key) {
     const value = source[key];
     return typeof value === "string" && value.length > 0 ? value : null;
 }
+/**
+ * The snake_case key, or the camelCase one when the adapter speaks that
+ * dialect (APRV-243).
+ *
+ * snake_case is read FIRST in both dialects, so an envelope carrying both
+ * spellings resolves the same way for every harness and cannot be used to show
+ * one command to the classifier and another to the harness.
+ */
+function readDialect(source, snake, camel, camelCase) {
+    const value = source[snake];
+    if (value !== undefined)
+        return value;
+    return camelCase ? source[camel] : undefined;
+}
+function readDialectString(source, snake, camel, camelCase) {
+    const value = readDialect(source, snake, camel, camelCase);
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
 /**
  * Parse the PreToolUse JSON.
  *
@@ -350,7 +1156,7 @@ function readString(source, key) {
  * 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) {
+function parseHookInput(raw, camelCase = false) {
     if (raw.trim().length === 0)
         return { ok: false, detail: "hook stdin was empty" };
     let parsed;
@@ -367,15 +1173,19 @@ function parseHookInput(raw) {
         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 toolName = readDialectString(fields, "tool_name", "toolName", camelCase);
+    if (toolName === null) {
+        return {
+            ok: false,
+            detail: camelCase ? "hook input has no tool_name or toolName" : "hook input has no tool_name",
+        };
+    }
+    const toolInputValue = readDialect(fields, "tool_input", "toolInput", camelCase);
     const toolInput = typeof toolInputValue === "object" && toolInputValue !== null && !Array.isArray(toolInputValue)
         ? toolInputValue
         : {};
-    const responseValue = fields["tool_response"];
-    const sessionId = readString(fields, "session_id");
+    const responseValue = readDialect(fields, "tool_response", "toolResponse", camelCase);
+    const sessionId = readDialectString(fields, "session_id", "sessionId", camelCase);
     return {
         ok: true,
         input: {
@@ -384,13 +1194,17 @@ function parseHookInput(raw) {
             // slower, which is the fail-closed direction.
             sessionId: sessionId ?? UNKNOWN_SESSION,
             sessionIdPresent: sessionId !== null,
+            // Grok Build sends `workspaceRoot` beside `cwd`. Only `cwd` is read:
+            // the classifier resolves paths against the directory the command will
+            // actually run in, and a workspace root is a different fact.
             cwd: readString(fields, "cwd") ?? "",
             toolName,
             toolInput,
-            toolUseId: readString(fields, "tool_use_id"),
-            hookEventName: readString(fields, "hook_event_name"),
+            toolUseId: readDialectString(fields, "tool_use_id", "toolUseId", camelCase),
+            hookEventName: readDialectString(fields, "hook_event_name", "hookEventName", camelCase),
+            model: readDialectString(fields, "model", "model", camelCase),
             harnessVersion: readString(fields, "version"),
-            interrupted: fields["is_interrupt"] === true,
+            interrupted: fields["is_interrupt"] === true || (camelCase && fields["isInterrupt"] === true),
             toolResponse: typeof responseValue === "object" && responseValue !== null && !Array.isArray(responseValue)
                 ? responseValue
                 : null,
@@ -842,22 +1656,387 @@ export function refineScratchDelete(result, roots) {
     }
     return { result: { ok: true, segments, classes }, notes };
 }
+// ===========================================================================
+// Read scope, the disk half (APRV-347)
+// ===========================================================================
+/**
+ * ## Why reads need a second pass too
+ *
+ * The pure classifier can settle an ABSOLUTE read target against the roots and
+ * nothing else. `cat ../other/secrets`, `grep -r needle ./link-to-elsewhere`
+ * and a bare `ls` all mean something only once a working directory and the
+ * filesystem's own links are in hand, and those are exactly the spellings an
+ * agent reaches for. So the read rule has the same two-part shape the delete
+ * rule has: the text decides what text can decide, and this pass — which
+ * resolves against the hook's OWN directory, follows links, and answers `null`
+ * for anything it cannot resolve — tightens `read.shell` back to
+ * `read.file.out_of_scope`.
+ *
+ * It only ever moves a segment toward the stricter class. A caller that skipped
+ * it would be no more permissive than one that runs it, which is what lets
+ * `hook classify` and `hook <harness>` share it without either becoming the
+ * authority.
+ */
+/** The rule a read tightened by this pass reports. */
+const READ_SCOPE_REJECTED_RULE = "read-out-of-scope-resolved";
+/**
+ * The read roots this process may vouch for, resolved.
+ *
+ * The gate root is the directory the hook resolved its POLICY from, never the
+ * harness-supplied `cwd`: a scope the subject of the gate could choose is not a
+ * scope (SPEC.md §11.1, self-reported fields never reduce scrutiny). The
+ * scratchpad and temp roots are the ones `resolveScratchRoots` already computes
+ * and already guards, so the two rules cannot disagree about where the agent's
+ * own scratch is. `declared` is `read_scope.roots` out of the loaded policy,
+ * which may only widen this set.
+ */
+export function resolveReadRoots(cwd, gateRoot, declared) {
+    const roots = effectiveReadRoots({
+        gateRoot: resolvedPath(gateRoot) ?? gateRoot,
+        systemRoots: resolveScratchRoots(cwd),
+        ...(declared === undefined ? {} : { declared }),
+    });
+    const out = [];
+    for (const root of roots) {
+        const resolved = resolvedPath(root) ?? root;
+        if (!out.includes(resolved))
+            out.push(resolved);
+    }
+    return out;
+}
+/**
+ * Where this target really is, or `null` when nothing can say.
+ *
+ * The same walk `targetStaysInScratch` does, and for the same reason: the file
+ * may not exist yet (or at all), so the nearest EXISTING ancestor is resolved
+ * and the unresolved tail re-appended. A symlink anywhere in that chain
+ * therefore cannot smuggle a read out of the root, which is the escape the pure
+ * half cannot see.
+ */
+function resolvedReadTarget(target, cwd) {
+    let existing = isAbsolute(target) ? target : resolvePathSegments(cwd, target);
+    const tail = [];
+    for (let depth = 0; depth < 64; depth += 1) {
+        if (existsSync(existing))
+            break;
+        const up = dirname(existing);
+        if (up === existing)
+            return null;
+        tail.unshift(basename(existing));
+        existing = up;
+    }
+    const resolved = resolvedPath(existing);
+    if (resolved === null)
+        return null;
+    return tail.length === 0 ? resolved : join(resolved, ...tail);
+}
+/**
+ * Tighten a `read.shell` segment to `read.file.out_of_scope` wherever the disk
+ * disagrees with the text.
+ *
+ * IMPURE by design and by contract. `roots` empty means the caller asked for no
+ * read scoping at all, and every segment is returned untouched — the same
+ * "absent yields today's answer" the classifier context promises.
+ */
+export function refineReadScope(result, roots, cwd) {
+    if (!result.ok)
+        return { result, notes: [] };
+    if (roots.length === 0)
+        return { result, notes: [] };
+    if (!result.segments.some((segment) => segment.class === "read.shell")) {
+        return { result, notes: [] };
+    }
+    const notes = [];
+    const segments = result.segments.map((segment) => {
+        if (segment.class !== "read.shell")
+            return segment;
+        const words = commandSegmentWords(segment.text);
+        const parsed = words === null ? undefined : words[0];
+        if (parsed === undefined)
+            return segment;
+        const positionals = parsed.args.filter((arg) => !arg.startsWith("-") || arg === "-");
+        const declaredTargets = readTargetsOf(parsed.bin, positionals, parsed.args);
+        if (declaredTargets === null)
+            return segment;
+        // No operand is not "no read": `ls`, `find` and a piped `grep needle` all
+        // read the working directory, so the working directory is what is checked.
+        const targets = declaredTargets.length === 0 ? ["."] : declaredTargets;
+        const reject = (path, detail) => {
+            notes.push(`${READ_SCOPE_REJECTED_RULE}: ${detail}`);
+            return {
+                ...segment,
+                class: READ_OUT_OF_SCOPE_CLASS,
+                rule: READ_SCOPE_REJECTED_RULE,
+                path,
+            };
+        };
+        for (const target of targets) {
+            const resolved = resolvedReadTarget(target, cwd);
+            if (resolved === null) {
+                return reject(target, `${target} does not resolve to any path this hook can see, so \`${segment.text}\` is ${READ_OUT_OF_SCOPE_CLASS}`);
+            }
+            if (!isInReadScope(resolved, roots)) {
+                return reject(resolved, `${target} resolves to ${resolved}, which is outside the read scope (${renderReadRoots(roots)}), so \`${segment.text}\` is ${READ_OUT_OF_SCOPE_CLASS}`);
+            }
+        }
+        return segment;
+    });
+    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 };
+}
+// ===========================================================================
+// Write scope, the disk half (APRV-402)
+// ===========================================================================
 /**
- * The classifier, its scratch context, and both impure refinements, in the one
+ * ## Why writes need a second pass too
+ *
+ * Deletes and reads each had one and writes did not, which left the oldest of
+ * the three rules the loosest. `files.write.workspace` was decided on the text
+ * alone: a relative destination is the workspace, said the classifier, and a
+ * relative destination is the workspace only while nothing on the way to it is
+ * a symlink out. `cp x build/y`, `tee build/y`, `mkdir build/y`, and since
+ * APRV-397 `tar -x -C build` and `npm pack --pack-destination build`, were all
+ * autonomous with `build` pointing anywhere at all.
+ *
+ * Not a regression and not new with the packaging rows (APRV-402): the hole is
+ * as old as the workspace-write row, and before APRV-397 every packaging
+ * command was denied as unclassified, so nothing that was refused became
+ * allowed by a symlink. What changed is that the rows now say `workspace` often
+ * enough for the gap to be worth the disk.
+ *
+ * ## The shape is the other two passes' shape
+ *
+ * Resolve the nearest EXISTING ancestor of each destination, re-append the
+ * unresolved tail, and TIGHTEN when the result is outside every root. It can
+ * only ever move a segment toward the stricter class, so a caller that skipped
+ * it is no more permissive than one that runs it, which is what lets
+ * `hook classify` and `hook <harness>` share it without either becoming the
+ * authority.
+ *
+ * ## What it costs, measured before it was written (APRV-402 AC1)
+ *
+ * The walk is 0.10 ms to 0.13 ms per destination on a warm cache (0.07 ms for
+ * an absolute one), over 20k iterations of each shape. A write segment names
+ * one or two destinations, so a write command pays about a fifth of a
+ * millisecond. APRV-209 measured a cold gated invocation at about 371 ms, of
+ * which 116 ms is the module graph and 51 ms is `hook.js` alone; this is under
+ * half a percent of that last term and it is paid only by segments the
+ * classifier already called a workspace write. The delete and read passes pay
+ * the same price per target and have since APRV-267 and APRV-347.
+ */
+/** The class an out-of-scope write tightens to, as `core/command-class.ts` spells it. */
+const OUT_OF_SCOPE_WRITE_CLASS = "files.delete.out_of_scope";
+/** The rule a write tightened by this pass reports. */
+const WRITE_SCOPE_REJECTED_RULE = "write-out-of-scope-resolved";
+/** The class this pass re-reads, and the only one it will touch. */
+const WORKSPACE_WRITE = "files.write.workspace";
+/**
+ * The classifier rules whose destinations this pass re-reads.
+ *
+ * Exactly the rows APRV-402 names: the workspace-write row (`mkdir`, `cp`,
+ * `mv`, `touch`, `tee`, `ln`, `chmod`, `truncate`, `rmdir`) and the six
+ * packaging answers APRV-397 added. `rm-workspace` and `redirect-write` reach
+ * the same class by the same text-only reasoning and are deliberately NOT here:
+ * they are the same hole in two more rules and they are their own decision, not
+ * one to take inside this task's diff.
+ */
+const WRITE_SCOPE_RULES = [
+    "workspace-write",
+    "tar-extract",
+    "tar-create",
+    "gunzip-write",
+    "base64-write",
+    "openssl-digest-out",
+    "npm-pack",
+];
+/**
+ * The roots a write may land in, resolved.
+ *
+ * The scratch roots are the ones `resolveScratchRoots` already computes and
+ * already guards, so this rule and the delete rule cannot disagree about where
+ * the agent's own scratch is. The working directory is the other one, and it is
+ * the root the classifier's own text rule already implies: "a relative
+ * destination is the workspace" means the workspace is wherever the command
+ * runs.
+ *
+ * `cwd` is harness-supplied, and reading a root out of it does not offend
+ * SPEC.md §11.1 invariant 4, because this pass only ever narrows. The baseline
+ * it narrows from is no check at all, so a poisoned `cwd` buys back exactly
+ * today's answer and never a looser one. Compare the read pass, which checks
+ * containment against the GATE root: that pass decides whether a read is in
+ * scope at all, so the scope has to be one the subject cannot choose. This one
+ * only takes an allowance away.
+ */
+export function resolveWriteRoots(cwd) {
+    const roots = resolveScratchRoots(cwd);
+    const here = resolvedPath(cwd);
+    if (here !== null && !roots.includes(here))
+        roots.unshift(here);
+    return roots;
+}
+/**
+ * Where this destination really is, or `null` when nothing can say.
+ *
+ * The same walk `targetStaysInScratch` and `resolvedReadTarget` do, for the
+ * same reason: the destination usually does NOT exist yet, so the nearest
+ * existing ancestor is resolved and the unresolved tail re-appended. A symlink
+ * anywhere in that chain therefore cannot smuggle a write out of the roots,
+ * which is the escape the pure half cannot see.
+ */
+function resolvedWriteTarget(target, cwd) {
+    let existing = isAbsolute(target) ? target : resolvePathSegments(cwd, target);
+    const tail = [];
+    for (let depth = 0; depth < 64; depth += 1) {
+        if (existsSync(existing))
+            break;
+        const up = dirname(existing);
+        if (up === existing)
+            return null;
+        tail.unshift(basename(existing));
+        existing = up;
+    }
+    const resolved = resolvedPath(existing);
+    if (resolved === null)
+        return null;
+    return tail.length === 0 ? resolved : join(resolved, ...tail);
+}
+/**
+ * The words of a write segment that could name a path on disk.
+ *
+ * Every argument that is not spelled as a flag, plus the value half of
+ * `--opt=value`. This is the delete pass's own filter, and it is deliberately
+ * coarser than the classifier's flag table: it reaches `-C dir`, `-o file` and
+ * `--pack-destination dir` without this file holding a second copy of that
+ * table to drift against. It over-includes (a `tar` archive being READ is a
+ * candidate too, and so is `chmod`'s mode), and over-including can only tighten
+ * a segment that would otherwise have been waved through.
+ *
+ * A bare `-` is not a path: it is stdin or stdout, and every binary in these
+ * rows that accepts it means the stream.
+ */
+function writeCandidates(args) {
+    const candidates = [];
+    for (const arg of args) {
+        if (arg === "-")
+            continue;
+        if (!arg.startsWith("-")) {
+            candidates.push(arg);
+            continue;
+        }
+        const equals = arg.indexOf("=");
+        if (equals === -1)
+            continue;
+        const value = arg.slice(equals + 1);
+        if (value.length > 0)
+            candidates.push(value);
+    }
+    return candidates;
+}
+/**
+ * Tighten a `files.write.workspace` segment to the out-of-scope write class
+ * wherever the disk disagrees with the text.
+ *
+ * IMPURE by design and by contract, exactly as the other two passes are. The
+ * class it tightens to is the one `core/command-class.ts` already answers for
+ * an out-of-scope packaging destination rather than a new name: a class no
+ * policy mentions resolves by `defaults.autonomy` (SPEC.md §7), so minting
+ * `files.write.out_of_scope` here would arrive AUTONOMOUS in every deployment
+ * with permissive defaults, which is the one way a tightening pass could
+ * loosen something.
+ *
+ * `roots` empty means the caller asked for no write scoping, and every segment
+ * comes back untouched: the same "absent yields today's answer" the read pass
+ * promises.
+ */
+export function refineWriteScope(result, roots, cwd) {
+    if (!result.ok)
+        return { result, notes: [] };
+    if (roots.length === 0)
+        return { result, notes: [] };
+    if (!result.segments.some((segment) => segment.class === WORKSPACE_WRITE && WRITE_SCOPE_RULES.includes(segment.rule))) {
+        return { result, notes: [] };
+    }
+    const notes = [];
+    const segments = result.segments.map((segment) => {
+        if (segment.class !== WORKSPACE_WRITE)
+            return segment;
+        if (!WRITE_SCOPE_RULES.includes(segment.rule))
+            return segment;
+        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) {
+            notes.push(`${WRITE_SCOPE_REJECTED_RULE}: \`${segment.text}\` could not be re-read, so it is ${OUT_OF_SCOPE_WRITE_CLASS}`);
+            return { ...segment, class: OUT_OF_SCOPE_WRITE_CLASS, rule: WRITE_SCOPE_REJECTED_RULE };
+        }
+        const reject = (path, detail) => {
+            notes.push(`${WRITE_SCOPE_REJECTED_RULE}: ${detail}`);
+            return {
+                ...segment,
+                class: OUT_OF_SCOPE_WRITE_CLASS,
+                rule: WRITE_SCOPE_REJECTED_RULE,
+                path,
+            };
+        };
+        for (const candidate of writeCandidates(parsed.args)) {
+            const resolved = resolvedWriteTarget(candidate, cwd);
+            if (resolved === null) {
+                return reject(candidate, `${candidate} does not resolve to any path this hook can see, so \`${segment.text}\` is ${OUT_OF_SCOPE_WRITE_CLASS}`);
+            }
+            if (!roots.some((root) => resolved === root || isBelow(resolved, root))) {
+                return reject(resolved, `${candidate} resolves to ${resolved}, which is outside the workspace and every scratch root (${roots.join(", ")}), so \`${segment.text}\` is ${OUT_OF_SCOPE_WRITE_CLASS}`);
+            }
+        }
+        return segment;
+    });
+    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 context, and all four impure refinements, in the one
  * order every caller must use.
  *
  * `hook classify` printing a different class from the one `hook claude-code`
  * decides would make the explainer a different program (APRV-108's note), and
- * that stays true now there are two refinements in the chain.
+ * that stays true now there are four refinements in the chain.
+ *
+ * `readRoots` is the one argument whose ABSENCE is the loose answer rather than
+ * the strict one (APRV-347), so it is passed explicitly at every call site: an
+ * empty list means "do not scope reads", which is what every caller outside a
+ * resolved gate scope wants and what this classifier did before the field
+ * existed.
  */
-export function classifyForHook(command, protectedPaths, cwd) {
+export function classifyForHook(command, protectedPaths, cwd, readRoots = []) {
     const roots = resolveScratchRoots(cwd);
-    const classified = classifyCommand(command, protectedPaths, { scratchRoots: roots });
+    const classified = classifyCommand(command, protectedPaths, {
+        scratchRoots: roots,
+        ...(readRoots.length === 0 ? {} : { readRoots }),
+    });
     const rewritten = refineRewrite(classified, cwd);
     const scratched = refineScratchDelete(rewritten.result, roots);
+    const scoped = refineReadScope(scratched.result, readRoots, cwd);
+    // APRV-402. Its roots are not `readRoots`: a read scope is a read notion and
+    // must not become a write authorization, so this pass asks its own question
+    // of the working directory and the scratch roots. Last in the chain because
+    // it is the narrowest, and because nothing after it would re-read a segment
+    // it has already tightened.
+    const written = refineWriteScope(scoped.result, resolveWriteRoots(cwd), cwd);
     return {
-        result: scratched.result,
-        notes: [...rewritten.notes, ...scratched.notes],
+        result: written.result,
+        notes: [...rewritten.notes, ...scratched.notes, ...scoped.notes, ...written.notes],
     };
 }
 // ===========================================================================
@@ -913,7 +2092,7 @@ function commandClassify(argv, streams, cwd) {
     if (command.length === 0) {
         return usageError(streams, "missing <command> argument for `approval hook classify`");
     }
-    const { options } = hookScope(parsed.flags, cwd);
+    const { root, options } = hookScope(parsed.flags, cwd);
     const load = loadPolicy(options.policy?.file === undefined
         ? { dir: options.policy?.dir ?? cwd }
         : { file: options.policy.file });
@@ -922,10 +2101,13 @@ function commandClassify(argv, streams, cwd) {
     }
     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")));
+    // APRV-267, APRV-347), run against the same directory and the same roots: an
+    // explainer that printed the pure class where the hook decides a refined one
+    // would be explaining a different program. A policy that did not load
+    // contributes no `read_scope`, so the scope is the built-in roots alone,
+    // which is the narrower answer and is what the hook itself would refuse on.
+    const readRoots = resolveReadRoots(cwd, policyRootOf(load, root), load.ok ? load.policy.read_scope?.roots : undefined);
+    streams.out(renderClassification(classifyForHook(command, protectedPaths, cwd, readRoots).result, boolFlag(parsed.flags, "--json")));
     return EXIT_OK;
 }
 function sleepSync(ms) {
@@ -1053,6 +2235,132 @@ function tierOf(target, cwd) {
  * non-protected target, which is why the loop floor could not see an Edit.
  */
 const WORKSPACE_WRITE_CLASS = "files.write.workspace";
+/**
+ * The Codex app-server's change set, when a call carries one (APRV-363,
+ * APRV-379).
+ *
+ * TWO SHAPES, because the protocol has two. The LEGACY `applyPatchApproval`
+ * carries `fileChanges`, a map of path to change, inline on the request. The
+ * ITEM-BASED API puts the same material on an earlier `item/started` frame as
+ * an ARRAY of `{path, kind, diff}`, and the bridge correlates that frame to the
+ * approval request by item id before handing it here (APRV-379). Both arrive as
+ * the server sent them and neither is re-rendered into the other.
+ *
+ * `null` for every other `apply_patch` call, which keeps the envelope path
+ * exactly as it was: the native hook's `apply_patch` tool sends a command
+ * string and reaches this function's `null` on the first test.
+ */
+function codexFileChanges(toolInput) {
+    const value = toolInput["file_changes"] ?? toolInput["fileChanges"];
+    if (value === null || typeof value !== "object")
+        return null;
+    if (Array.isArray(value))
+        return value.length === 0 ? null : value;
+    const map = value;
+    return Object.keys(map).length === 0 ? null : map;
+}
+/**
+ * The paths a change set names, in the order this runtime will classify them,
+ * or `null` when an entry names none (APRV-379).
+ *
+ * The map's keys ARE its paths, sorted so one change set is one description
+ * whatever key order the server used. The array's entries each carry a `path`
+ * string, and the order is the server's own: an array is a sequence and
+ * reordering it would be this runtime describing a change set nobody sent. An
+ * entry that is not an object, or whose `path` is not a string, yields `null`
+ * and the caller refuses the whole set, because a change set with one
+ * unreadable member is a change set this runtime cannot say the extent of.
+ */
+function codexChangePaths(changes) {
+    if (!Array.isArray(changes))
+        return Object.keys(changes).sort();
+    const paths = [];
+    for (const entry of changes) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            return null;
+        const declared = entry["path"];
+        if (typeof declared !== "string")
+            return null;
+        paths.push(declared);
+    }
+    return paths;
+}
+/**
+ * What a change SET asks for: one class per path it names, and the change bound
+ * whole (APRV-363, APRV-379).
+ *
+ * The class rule is the file tools' rule and not a second one: a protected
+ * target takes its derived protected class, every other target is
+ * `files.write.workspace`, and the policy decides the autonomy of either. The
+ * payload is the change rather than the touch, for the reason
+ * {@link fileToolGate} states at length, plus `content_sha256` over the set as
+ * it ARRIVED, so a human's grant binds the bytes the server sent and a later
+ * reader can check that it did. The set goes into the payload in the shape it
+ * arrived in, map or array; nothing here reads `diff`, `kind` or any other
+ * member, because one observed `add` is not a licence to parse Codex patch
+ * semantics in this repository.
+ *
+ * Fails closed on a path this runtime cannot place: one that lands outside the
+ * directory the server named, or one carrying a NUL. A change whose target
+ * cannot be resolved cannot be classified, and a classification against the
+ * wrong tree is the failure this whole file exists to avoid.
+ *
+ * An ABSOLUTE path is accepted when it resolves INSIDE that directory, which
+ * APRV-379 changed: the observed item frame names absolute paths
+ * (`docs/codex-app-server-bridge.md`, question 1), and an absolute path inside
+ * the directory is exactly as placeable as a relative one. Containment is what
+ * was ever doing the work here, and it still decides: a path outside is refused
+ * whichever way it was spelled.
+ */
+function describeCodexFileChanges(changes, protectedPaths, cwd) {
+    const classes = [];
+    const notes = [];
+    const paths = [];
+    const declaredPaths = codexChangePaths(changes);
+    if (declaredPaths === null) {
+        return {
+            kind: "deny",
+            code: "hook-io",
+            detail: "the file change set carries an entry that names no path string, so the extent of the change cannot be stated; nothing was classified",
+        };
+    }
+    for (const declared of declaredPaths) {
+        if (declared.length === 0 || declared.includes("\0")) {
+            return {
+                kind: "deny",
+                code: "hook-io",
+                detail: `the file change names ${JSON.stringify(declared)}, which is not a path this runtime can place; a change whose target cannot be placed cannot be classified`,
+            };
+        }
+        const resolved = resolvePathSegments(cwd, declared);
+        if (resolved !== cwd && !resolved.startsWith(`${cwd}${sep}`)) {
+            return {
+                kind: "deny",
+                code: "hook-io",
+                detail: `the file change names ${JSON.stringify(declared)}, which resolves outside ${cwd}`,
+            };
+        }
+        paths.push(declared);
+        const cls = protectedPathClass(resolved, protectedPaths) ?? WORKSPACE_WRITE_CLASS;
+        if (!classes.includes(cls))
+            classes.push(cls);
+        notes.push(`change ${declared} (${cls})`);
+    }
+    return {
+        kind: "gated",
+        classes,
+        payload: {
+            tool: "apply_patch",
+            rule: "codex app-server file change",
+            cwd,
+            paths,
+            content_sha256: payloadHash(changes),
+            changes,
+        },
+        headline: `apply_patch ${String(paths.length)} file change(s)`,
+        notes,
+    };
+}
 /**
  * What a non-Bash tool call asks for, or `null` when it names no file at all.
  *
@@ -1149,6 +2457,95 @@ function fileToolGate(toolName, toolInput, protectedPaths, cwd) {
         summary: summaryFor(tier, toolName, file),
     };
 }
+/**
+ * The first entry of a `paths` array that falls outside the read scope, or
+ * `null` when every entry is inside it (APRV-350).
+ *
+ * Separate from the single-path arm because the ANSWER is different: one path
+ * either is or is not in scope, while a list is out of scope if ANY member is.
+ * Returning the offending member rather than a boolean keeps the gated question
+ * specific — an approver is asked about the directory that actually left the
+ * scope, not about the whole list.
+ */
+function firstOutOfScope(toolInput, roots, cwd) {
+    const paths = toolInput["paths"];
+    if (!Array.isArray(paths))
+        return null;
+    for (const entry of paths) {
+        if (typeof entry !== "string" || entry.trim() === "")
+            continue;
+        const resolved = resolvedReadTarget(entry, cwd);
+        if (resolved === null || !isInReadScope(resolved, roots))
+            return entry;
+    }
+    return null;
+}
+function readToolGate(toolName, toolInput, roots, cwd) {
+    if (roots.length === 0)
+        return null;
+    const declared = readString(toolInput, "file_path") ??
+        readString(toolInput, "notebook_path") ??
+        readString(toolInput, "path") ??
+        // APRV-350: Muse's `search` names an ARRAY under `paths`, and the live
+        // capture caught one pointing clean out of the workspace. The FIRST entry
+        // that resolves outside the scope is the one gated: a search over five
+        // directories where one is out of scope is an out-of-scope read, and
+        // gating the first in-scope entry instead would have let it through. An
+        // unreadable entry counts as out of scope for the same fail-closed reason
+        // the single-path arm below resolves that way.
+        firstOutOfScope(toolInput, roots, cwd);
+    if (declared === null)
+        return null;
+    // FAIL CLOSED on an unresolvable path (the task's AC1, and SPEC.md §11.1):
+    // a target nothing on this disk can place is a target nothing can say is
+    // inside the scope, so it is out of it.
+    const resolved = resolvedReadTarget(declared, cwd);
+    if (resolved !== null && isInReadScope(resolved, roots))
+        return null;
+    const file = resolved ?? absolute(declared, cwd);
+    const input = { ...toolInput };
+    delete input["description"];
+    return {
+        file,
+        declared,
+        // The binding bytes name the RESOLVED path as well as the tool's own input,
+        // so an approver reads where the data actually comes from and a grant over
+        // one spelling cannot be spent on another.
+        payload: { tool: toolName, rule: "read-scope", file, input },
+        summary: `${toolName} ${file} (outside the read scope)`,
+    };
+}
+/**
+ * A read tool call naming a credential file (APRV-445 refutation, B2): the
+ * Hermes home's `.env` and `auth.json`, and the approval home's vault, keys and
+ * environment map. `null` for anything else.
+ */
+function credentialReadGate(toolName, toolInput, cwd) {
+    const declared = readString(toolInput, "file_path") ??
+        readString(toolInput, "notebook_path") ??
+        readString(toolInput, "path");
+    if (declared === null)
+        return null;
+    // APRV-445 recheck SF2(e, f): judged through realpath, so a symlinked
+    // parent cannot launder the path, and a directory of credentials handed to a
+    // read tool (a search, a glob, a grep) is gated as the credentials are.
+    const file = canonicalPath(absolute(declared, cwd));
+    // Recheck 3 (SF1a): only a directory that holds credentials (a home root, an
+    // approval home, a home's `approval/`, or a directory under a home holding a
+    // credential file); `skills/`, `workspace/` and the like are ordinary.
+    if (!isCredentialPath(file) && !holdsCredentials(file))
+        return null;
+    const input = { ...toolInput };
+    delete input["description"];
+    return {
+        payload: { tool: toolName, rule: "credential", file, input },
+        summary: `${toolName} ${file} (credential)`,
+    };
+}
+/** The verdict note for a gated read: what was asked for, and against what. */
+function readScopeNote(gated, roots) {
+    return `read-scope: ${gated.declared} resolves to ${gated.file}, which is outside the read scope (${renderReadRoots(roots)})`;
+}
 /** The headline for a tier: the qualifier first, the touch after it. */
 function summaryFor(tier, toolName, file) {
     if (tier.worktree !== null) {
@@ -1276,6 +2673,12 @@ function abandonedRequests(run, records, now, keepHash) {
             continue;
         if (record.actor !== run.actor)
             continue;
+        // APRV-445. Under `approval serve` the hook and `propose` act as ONE actor,
+        // and a proposal's request is harness-executed too, so without this every
+        // proposal pending past the hook's wait plus grace (minutes) would be swept
+        // as abandoned by the next gated tool call, days before its TTL.
+        if (isProposalTask(record.task))
+            continue;
         const key = record.action_key;
         if (typeof key !== "string" || key.length === 0)
             continue;
@@ -1550,7 +2953,7 @@ function recordUnattended(run, task, classes, hash) {
  * 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) {
+function announceWait(streams, run, waiting, expiryOf) {
     const where = run.channels.length === 0
         ? "no channel (this policy configures none, so nothing is delivering the question)"
         : `channel ${run.channels.join(", ")}`;
@@ -1558,7 +2961,21 @@ function announceWait(streams, run, 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 at = expiryOf.get(action.actionKey);
+        // Second review pass (F7): which of the two ends first decides the sentence.
+        // "Open for a 5m grace" beside "expires at T+240s" was two claims about one
+        // question that could not both hold; the shorter one is the one stated.
+        const holdsOpen = at !== undefined && windowEndsBeforeGrace(run)
+            ? `. The request expires at ${at}, which comes before the ${minutesText(run.graceMs)} retry grace would run out, so that is how long it stays open for a retry; a decision after it is refused rather than granted.`
+            : ` and leaving the request open for a ${minutesText(run.graceMs)} retry grace.${expiryClause(at)}`;
+        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 ${waitText(run)} before denying with hook-timeout${holdsOpen}${adopted}\n`);
+    }
+    // APRV-423, third review pass. The wait is CLAMPED to what the ceiling
+    // leaves (see `HookRun.waitMs`), so the runtime acts rather than warns: a
+    // wait the harness would have cut short is shortened here, and the operator
+    // is told once so the configured --timeout is not mistaken for the wait.
+    if (run.harnessCapMs !== null && run.waitMs < run.timeoutMs) {
+        streams.err(`approval: this hook's ${String(run.timeoutMs)}ms --timeout is longer than the ${String(run.harnessCapMs)}ms harness ceiling leaves after the ${String(HARNESS_CAP_MARGIN_MS)}ms margin, so it waits ${String(run.waitMs)}ms instead and answers before the harness stops listening. Lower --timeout, or state the real ceiling with --harness-cap.\n`);
     }
     const socket = drawSocketPathFor(run.logPath);
     const listener = drawSocketUsable(socket);
@@ -1567,44 +2984,68 @@ function announceWait(streams, run, waiting) {
     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)
+ * ` The request expires at <instant> ...`, or `""` when nothing bounds it
+ * (APRV-423).
  *
- * 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.
+ * One phrasing for the three places that state the deadline — the announce
+ * line, the timeout deny and the expiry deny — so an agent reading two of them
+ * in one session is reading the same sentence about the same moment.
+ */
+function expiryClause(at) {
+    if (at === undefined)
+        return "";
+    return ` The request expires at ${at}, after which a decision on it is refused rather than granted.`;
+}
+/**
+ * Does the window a capped request is judged by close before the retry grace
+ * this invocation would hold the question open for? (APRV-423, second review
+ * pass.)
+ *
+ * Both are durations measured from the `approval.requested` record's own `ts`
+ * (`harnessCappedTtlMs` for the window, `abandonedAfterMs` for the grace), so
+ * the comparison needs no clock. `false` for an uncapped run whatever the
+ * policy's TTL: the uncapped sentences are left byte-for-byte as APRV-287 wrote
+ * them, which `tests/cli-hook.test.ts`'s snapshot case depends on. Computed from
+ * this invocation's own flags, so for an ADOPTED question opened under other
+ * flags it is the current invocation's reading of the two windows.
+ */
+/**
+ * `55000ms wait`, or `0ms wait (a 240000ms --timeout clamped to what the 30000ms
+ * harness ceiling leaves)` when the ceiling shortened it (APRV-423, third
+ * review pass). One spelling for the announce line, the lagging note and the
+ * `hook-timeout` denies, so a reader is never told a wait this process did not
+ * make.
+ */
+function waitText(run) {
+    if (run.waitMs === run.timeoutMs || run.harnessCapMs === null) {
+        return `${String(run.waitMs)}ms wait`;
+    }
+    return `${String(run.waitMs)}ms wait (a ${String(run.timeoutMs)}ms --timeout clamped to what the ${String(run.harnessCapMs)}ms harness ceiling leaves)`;
+}
+function windowEndsBeforeGrace(run) {
+    if (run.harnessCapMs === null)
+        return false;
+    const window = harnessCappedTtlMs(run.ttlMs, run.harnessCapMs);
+    return window !== null && window <= abandonedAfterMs(run.timeoutMs, run.graceMs);
+}
+/** ` (expired at <instant>)`, or `""`. The parenthetical form of the above. */
+function expiryAt(at) {
+    return at === undefined ? "" : ` (expired at ${at})`;
+}
+/**
+ * The hook's own rendering of a verdict: one decision object on stdout, in the
+ * dialect of the harness that asked.
  *
- * 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.
+ * The one place a verdict becomes bytes, so the Codex guard inside
+ * {@link allow} — an allow that lost its exact bound `tool_input.command` is an
+ * I/O failure rather than a permission — still stands over every path.
  */
-function gateAndWait(streams, run, classes, 
+function renderVerdict(streams, adapter, codexCommand, verdict) {
+    return verdict.permission === "allow"
+        ? allow(streams, verdict.reason, adapter.kind, codexCommand)
+        : deny(streams, verdict.code, verdict.detail, adapter.kind);
+}
+export function gateHarnessCall(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
@@ -1655,18 +3096,22 @@ floor = null) {
     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, run.codexCommand);
+    const sayAllow = (reason) => ({ permission: "allow", reason });
     /**
-     * Every deny this function can print, with the floor's own sentence appended
+     * Every deny this function can reach, 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);
+    const sayDeny = (code, detail) => ({
+        permission: "deny",
+        code,
+        detail: 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)}`,
+    });
     // 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
@@ -1685,7 +3130,12 @@ floor = null) {
         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);
+        // APRV-410: the window this invocation is configured for bounds which
+        // GRANT it may carry, so an answer that landed after the asking process
+        // was gone is not adopted by a later one. The sweep above takes back the
+        // pending questions; this refuses the grants that were written on questions
+        // nobody was holding. The two halves are the same fact from both sides.
+        const carry = findHarnessCarry(intake.records, hash, cls, intakeTs, run.ttlMs, abandonedAfterMs(run.timeoutMs, run.graceMs));
         if (carry === null)
             return { cls, actionKey: `${task}:${cls}`, origin: "new" };
         return {
@@ -1697,6 +3147,62 @@ floor = null) {
     const fresh = actions.filter((action) => action.origin === "new");
     const adopted = actions.filter((action) => action.origin === "adopted");
     const carried = actions.filter((action) => action.origin === "carried");
+    /**
+     * The window every request this invocation opens will be judged by
+     * (APRV-423): the policy's TTL, narrowed by the harness ceiling this process
+     * runs under. `null` means nothing bounds it, which is a policy with no
+     * `approval_ttl` under a harness that documents no maximum and an operator
+     * who stated none.
+     */
+    const ownTtlMs = harnessCappedTtlMs(run.ttlMs, run.harnessCapMs);
+    /**
+     * When each waited-on key lapses, ISO-8601, for the lines this invocation
+     * prints. Filled from the runtime's OWN write-boundary timestamps — the `ts`
+     * on the record `request` returned, and the request record intake already
+     * read for an adopted key — so a deny that names a deadline names the one the
+     * gate will judge by, and no second read of the log pays for the sentence.
+     *
+     * CAPPED REQUESTS ONLY (APRV-423). The sentence exists to state a deadline
+     * its reader cannot work out from the policy: under a harness ceiling the
+     * window is neither `approval_ttl` nor the harness's own timeout, and an
+     * agent told "it lapsed" with no instant has no way to tell a four-minute
+     * window from the hour its policy declares. A request the policy alone bounds
+     * already has its deadline stated where its reader can see it (the approver's
+     * own card, `approval status`, the queue), so the hook's lines are left
+     * exactly as APRV-281 and APRV-287 wrote them — which also keeps every
+     * uncapped deny byte-for-byte reproducible across two invocations, the
+     * property `tests/cli-hook.test.ts` pins when it compares a cold read's
+     * verdict with a snapshot-resumed one.
+     */
+    const expiryOf = new Map();
+    // APRV-423, and the last thing checked before this invocation opens a
+    // question. A ceiling at or below the margin leaves no window: the request
+    // would have to lapse before the harness kills this process, and there is no
+    // "before" left. Refused rather than widened, because a hook that ignored its
+    // own ceiling is a hook whose question outlives its asker, which is the whole
+    // failure this cap exists to end (APRV-410). Placed here rather than at the
+    // top of the function so it refuses exactly the act it is about: an ADOPTED
+    // question was opened by a process that cleared this check, and a CARRIED
+    // grant is a human's answer that already exists.
+    if (fresh.length > 0 && run.harnessCapMs !== null && !harnessCapFitsMargin(run.harnessCapMs)) {
+        // Second review pass: the deny names the actions it refused for (so a reader
+        // can still see which class routed this call to a human), says whether the
+        // ceiling was stated or assumed, and ends with the harness's own repair
+        // where the adapter has one.
+        const needing = fresh.map((action) => `${action.actionKey} (${action.cls})`).join(", ");
+        const origin = run.harnessCapStated
+            ? "stated with --harness-cap"
+            : "assumed from the harness's documented defaults because no --harness-cap was passed";
+        // APRV-427 review: where time spent before this invocation was charged,
+        // the operator's number is named as theirs and the remainder as what is
+        // left of it, rather than reporting the remainder as what they stated.
+        const source = run.harnessCapCeilingMs === null
+            ? origin
+            : `~${String(run.harnessCapMs)}ms left of the ${String(run.harnessCapCeilingMs)}ms ceiling ${origin}; the rest was spent before this hook began, waiting in approval serve's queue or for its store lock`;
+        const repair = run.harnessCapRepair ??
+            `Raise the harness entry's timeout past ${String(HARNESS_CAP_MARGIN_MS)}ms and state the real one with --harness-cap, or route this class somewhere a human is not on the critical path.`;
+        return sayDeny("hook-harness-cap-too-short", `${needing} would need a human, but this hook runs under a ${String(run.harnessCapMs)}ms harness ceiling (${source}), and a request must lapse at least ${String(HARNESS_CAP_MARGIN_MS)}ms before that ceiling so the runtime records the expiry while the harness is still listening. That leaves no window in which a human could answer, so nothing was registered, nothing was requested and no question reached a phone. ${repair}`);
+    }
     // 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.
@@ -1745,6 +3251,12 @@ floor = null) {
             payload_hash: hash,
             payload: { value: payload },
             execution: "harness",
+            // APRV-423. The ceiling this process runs under, recorded so the gate,
+            // the daemon's sweep and every channel judge the question by a window
+            // that ends before the harness kills the asker. Omitted entirely when
+            // there is no ceiling to state: an absent field is the pre-APRV-423
+            // shape, and the policy's TTL governs alone.
+            ...(run.harnessCapMs === null ? {} : { harnessCapMs: run.harnessCapMs }),
             ...(floorApplies(action.cls) ? { loopFloor: true } : {}),
         }, run.actor, run.options);
         if (!result.ok) {
@@ -1754,8 +3266,31 @@ floor = null) {
             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)
+        if (result.record !== null) {
             ownKeys.push(action.actionKey);
+            // The deadline in words, from the `ts` the runtime stamped on the record
+            // it just wrote. Never from this process's own clock: a gate-typed event
+            // carries the write boundary's instant (SPEC.md §11.1 invariant 2), and a
+            // deny that named a deadline measured from anything else would be naming
+            // a moment the gate does not judge by.
+            if (ownTtlMs !== null && run.harnessCapMs !== null) {
+                const lapses = Date.parse(result.record.ts);
+                if (!Number.isNaN(lapses)) {
+                    expiryOf.set(action.actionKey, new Date(lapses + ownTtlMs).toISOString());
+                }
+            }
+        }
+    }
+    // An adopted question was opened by an earlier invocation, under whatever
+    // ceiling THAT one ran under, so its deadline is read off the request record
+    // intake already verified rather than recomputed from this process's flags.
+    for (const action of adopted) {
+        const derivation = requestState(intake.records, action.actionKey, intakeTs, run.ttlMs);
+        if (derivation.declared.harness_cap_ms === null)
+            continue;
+        const at = requestExpiresAt(derivation);
+        if (at !== null)
+            expiryOf.set(action.actionKey, at);
     }
     /** Every key that must be granted before this hook says yes. */
     const waitKeys = [...adopted.map((action) => action.actionKey), ...ownKeys];
@@ -1795,21 +3330,50 @@ floor = null) {
     // 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;
+    announceWait(streams, run, actions.filter((action) => waitKeys.includes(action.actionKey)), expiryOf);
+    const deadline = Date.now() + run.waitMs;
+    // APRV-427. From the first poll to the last this invocation only READS the
+    // verified log and sleeps, so an embedding caller (`approval serve`) may let
+    // other work on the same store run meanwhile. `leaveWait` hands the stretch
+    // back before anything below appends, and once more whichever way the loop
+    // is left; it is a no-op from the CLI, where there is no seam.
+    let waiting = false;
+    const leaveWait = () => {
+        if (!waiting)
+            return;
+        waiting = false;
+        run.waitSeam?.leaveWait();
+    };
     // 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) => {
+        leaveWait();
         withdrawPending(run, streams, ownKeys, `the requesting hook process received ${signal} while waiting; the session is ending, so no retry will adopt this request`);
+        // APRV-445. On Hermes an exit with nothing on stdout is an ALLOW unless the
+        // exit is 2, and a harness tearing down may still read the verdict. So the
+        // block directive goes out first, written synchronously because
+        // `process.exit` below does not wait for a stream to drain.
+        if (run.harness === "hermes") {
+            const directive = harnessBlockDirective("hook-interrupted", `the hook received ${signal} while waiting for a decision; nothing authorizes this call`, "hermes");
+            try {
+                writeSync(1, directive.stdout);
+            }
+            catch {
+                // stdout is gone; the exit code below is the whole verdict.
+            }
+            process.exit(HERMES_DENY_EXIT);
+        }
         process.exit(EXIT_USAGE);
     };
     const onTerm = () => onSignal("SIGTERM");
     const onInt = () => onSignal("SIGINT");
-    process.on("SIGTERM", onTerm);
-    process.on("SIGINT", onInt);
+    // Prepended: under Hermes an earlier guard (`hermesFailClosed`) listens for
+    // the same signals, and this handler, which also withdraws, must answer first.
+    process.prependListener("SIGTERM", onTerm);
+    process.prependListener("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
@@ -1817,22 +3381,96 @@ floor = null) {
      * matters under sixty copies of itself.
      */
     let saidLagging = false;
+    /** Consecutive torn-tail reads, for {@link TORN_TAIL_RETRIES}. */
+    let tornReads = 0;
+    /** The last whole verified view this wait read, for a torn read at the deadline. */
+    let lastClean = null;
+    const callerGone = () => run.waitSeam?.cancelled?.() === true;
+    /** The verdict for a caller that went away: nothing spent, nothing withdrawn. */
+    const sayGone = () => sayDeny("hook-timeout", `the caller that asked went away before ${waitKeys.join(", ")} could be answered to it. NOTHING WAS SPENT AND NOTHING WAS WITHDRAWN: the question, or a grant already recorded on it, is left for a retry of this exact command in this exact directory to adopt within the ${minutesText(run.graceMs)} retry grace.`);
+    const pollRead = run.waitSeam?.pollRead ?? ((path) => readVerifiedRecords(path));
+    /**
+     * The deny for a wait that ran out with the question left OPEN, after
+     * `lead` (APRV-427 review: one builder, so every route to it says the same
+     * thing). Two forms, as the second review pass (F7) fixed them: where the
+     * capped window closes before the retry grace would, the sentence names the
+     * expiry as what bounds the question; otherwise it names the grace and adds
+     * the expiry where there is one.
+     */
+    const keptOpen = (lead, stillLagging) => {
+        // APRV-423. The deadline the still-open question is under, named in the
+        // same breath as the wait that ran out: the two are different numbers and
+        // the second one is the one that decides whether a retry can still adopt
+        // this question. Under a harness ceiling it is also the instant the runtime
+        // will append `approval.expired` at, which is what keeps this deny and that
+        // record from disagreeing about one request.
+        const deadlines = waitKeys
+            .map((key) => expiryOf.get(key))
+            .filter((at) => at !== undefined);
+        const expiresAt = [...new Set(deadlines)].sort().join(", ");
+        if (deadlines.length > 0 && windowEndsBeforeGrace(run)) {
+            return sayDeny("hook-timeout", `${lead} This tool call is denied and NOTHING WAS WITHDRAWN: the harness ceiling this hook runs under bounds the question, and the request(s) expire at ${expiresAt}, which comes before the ${minutesText(run.graceMs)} retry grace would run out, so that is how long they stay open. A decision inside that window authorizes a retry of this exact command in this exact directory, once; retry it after the approver answers, and the retry adopts the same question rather than asking a second one. A decision after ${expiresAt} is refused rather than granted, the runtime records the lapse as approval.expired, and a retry then asks the question fresh.${stillLagging}`);
+        }
+        const expiresText = deadlines.length === 0
+            ? ""
+            : ` The harness ceiling this hook runs under bounds the question too: the request(s) expire at ${expiresAt}, and a decision after that is refused rather than granted — the runtime records the lapse as approval.expired.`;
+        return sayDeny("hook-timeout", `${lead} 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.${expiresText} Retry it after the approver answers; the retry adopts the same question rather than asking a second one. Past the grace the question is taken back (approval.withdrawn, reason timeout) BY THE NEXT GATED TOOL CALL THIS ACTOR (${run.actor}) MAKES, which is the only process that may: a withdrawal is the requester's own (APRV-106), so no daemon and no channel can do it for you. Until that next call the request stays pending, and a decision that lands past the grace is recorded as a grant — it authorizes nothing, because a retry past the grace asks again rather than carrying a grant nobody was holding (APRV-410).${stillLagging}`);
+    };
+    run.waitSeam?.enterWait();
+    waiting = true;
     try {
         for (;;) {
-            const read = readVerifiedRecords(run.logPath);
+            if (callerGone())
+                return sayGone();
+            let read = pollRead(run.logPath);
+            if (!read.ok && read.code === "log-torn-tail" && tornReads < TORN_TAIL_RETRIES) {
+                if (Date.now() < deadline) {
+                    // Another writer's line, caught half-landed. Read again next tick;
+                    // see TORN_TAIL_RETRIES. Said once, like the lagging view below.
+                    if (tornReads === 0) {
+                        streams.err(`approval: the log's last line was incomplete when this hook read it (another writer mid-append); reading again rather than giving up on ${task}\n`);
+                    }
+                    tornReads += 1;
+                    sleepSync(Math.min(run.intervalMs, Math.max(0, deadline - Date.now())));
+                    continue;
+                }
+                // AT the deadline (APRV-427 review). A clean read at this tick would
+                // take the timeout path and leave the question open for the retry
+                // grace; someone else's half-written line must not turn that into a
+                // withdrawal. So the tick is judged by the last whole view this wait
+                // read, and the timeout path below runs on it. Only a tail that stays
+                // torn past the retries, a write nobody is going to finish, still
+                // withdraws and denies.
+                if (lastClean === null) {
+                    return keptOpen(`no decision on ${waitKeys.join(", ")} within the hook's ${waitText(run)}, and the log's last line was incomplete when the wait ended (another writer mid-append).`, "");
+                }
+                read = lastClean;
+            }
             if (!read.ok) {
+                leaveWait();
                 withdrawPending(run, streams, ownKeys, `the hook could not read the log while waiting on ${task}`);
                 return sayDeny("hook-io", read.message);
             }
+            tornReads = 0;
+            lastClean = read;
             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 derived = waitKeys.map((key) => {
+                const derivation = requestState(read.records, key, ts, run.ttlMs);
+                // APRV-423: the deadline this read judged by, kept beside the state so
+                // the verdict and the sentence that explains it come from one
+                // derivation. A key whose record this view does not carry yet answers
+                // `null`, and the lagging branch below is what handles that.
+                if (derivation.declared.harness_cap_ms !== null) {
+                    const at = requestExpiresAt(derivation);
+                    if (at !== null)
+                        expiryOf.set(key, at);
+                }
+                return { key, state: derivation.state };
+            });
             const states = derived.map((entry) => entry.state);
             /**
              * Keys this process ESTABLISHED exist, that this read does not carry
@@ -1866,7 +3504,7 @@ floor = null) {
                 .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`);
+                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 ${waitText(run)}. 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
@@ -1883,11 +3521,27 @@ floor = null) {
                     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`);
+                    // APRV-423. WHICH deadline it lapsed at, because under a harness
+                    // ceiling that is not the policy's TTL and an agent told only "it
+                    // lapsed" would read a four-minute window as an hour-long one that
+                    // somehow failed. The runtime, not this hook, appends the
+                    // `approval.expired` record: `decide` materialises it the moment a
+                    // late tap is refused, and the daemon's sweep materialises it on its
+                    // own cadence. A hook never writes one.
+                    const lapsed = derived
+                        .filter((entry) => entry.state === "expired")
+                        .map((entry) => `${entry.key}${expiryAt(expiryOf.get(entry.key))}`);
+                    return sayDeny("hook-expired", `the request for ${task} lapsed before a decision (${lapsed.join(", ")}). A decision arriving now is refused rather than granted, and the runtime records the lapse as approval.expired; run the command again to ask the question fresh.`);
                 }
                 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.
+                    leaveWait();
+                    // Looked at again now the lock is held: re-taking it may have waited,
+                    // and a caller that left meanwhile must not have its grant spent on a
+                    // verdict nobody will receive. The retry is who spends it.
+                    if (callerGone())
+                        return sayGone();
                     const failed = consumeGrants(run, spendKeys, hash, task);
                     if (failed !== null) {
                         return sayDeny(`hook-gate-refused:${failed.code}`, failed.message);
@@ -1917,6 +3571,7 @@ floor = null) {
                 // 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.
+                leaveWait();
                 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
@@ -1927,9 +3582,9 @@ floor = null) {
                     ? ""
                     : ` 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 ${waitText(run)}, 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}`);
+                return keptOpen(`no decision on ${waitKeys.join(", ")} within the hook's ${waitText(run)}.`, stillLagging);
             }
             sleepSync(Math.min(run.intervalMs, Math.max(0, deadline - Date.now())));
         }
@@ -1939,10 +3594,12 @@ floor = null) {
         // 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.
+        leaveWait();
         withdrawPending(run, streams, ownKeys, `the requesting hook process failed while waiting (${cause instanceof Error ? cause.message : String(cause)})`);
         throw cause;
     }
     finally {
+        leaveWait();
         process.off("SIGTERM", onTerm);
         process.off("SIGINT", onInt);
     }
@@ -2093,9 +3750,143 @@ function report(streams, code, detail, extra = {}) {
  * 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.
  */
+/**
+ * Muse's outcome, which it actually sends (APRV-350).
+ *
+ * The shell tool's `tool_response` is a JSON STRING, not an object, carrying
+ * `exit_code`, `terminal_status`, `output` and `truncated`. The generic reader
+ * above would see a string, find neither `interrupted` nor `error` on it, and
+ * call every command completed — including the ones that failed. So Muse gets
+ * its own reading, and it is the richer one: this harness sends both facts
+ * Codex lacks.
+ *
+ * `terminal_status` leads because it distinguishes a command that ran from one
+ * that was killed or timed out; `exit_code` decides the rest. Anything this
+ * cannot read is UNREADABLE rather than assumed complete, which appends nothing
+ * and leaves the path as vacuous as it was — the same choice the generic reader
+ * makes, for the same reason. Nothing of `output` is read.
+ */
+function readMuseReportedOutcome(input) {
+    const raw = input.toolResponseRaw;
+    // The file tools answer with an object (`filePath`, `structuredPatch`) and
+    // the read tools with a plain string of file content. Neither carries an
+    // outcome, and the event name is the only fact available for them.
+    if (typeof raw !== "string") {
+        return { ok: true, outcome: "completed" };
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        // A non-JSON string is a read tool's content. It says nothing about
+        // success, and the event fired at all, so the event name stands.
+        return { ok: true, outcome: "completed" };
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        return { ok: true, outcome: "completed" };
+    }
+    const fields = body;
+    const status = fields["terminal_status"];
+    if (typeof status === "string" && status !== "completed") {
+        // `aborted`, `timed_out`, and whatever else Meta adds: a command that did
+        // not finish on its own terms neither completed nor failed, exactly as an
+        // interrupt does not.
+        return {
+            ok: false,
+            detail: `terminal_status is ${JSON.stringify(status)}, so the command neither completed nor failed on its own terms`,
+        };
+    }
+    const exitCode = fields["exit_code"];
+    if (typeof exitCode === "number") {
+        return { ok: true, outcome: exitCode === 0 ? "completed" : "failed" };
+    }
+    return { ok: true, outcome: "completed" };
+}
+/**
+ * Hermes's outcome, read off `post_tool_call` where the event carries one
+ * (APRV-398).
+ *
+ * The envelope's result field is read for its SHAPE only, exactly as the generic
+ * reader reads Claude Code's: an `exit_code` decides a shell call, an `error`
+ * string or an `error` flag decides anything, and a result this cannot read is
+ * UNREADABLE rather than assumed complete. Nothing of the tool's output text is
+ * read, and nothing from it reaches the log.
+ *
+ * Unreadable is the safe answer in both directions at once and the reasoning is
+ * the generic reader's own: a failure nobody observed trips an escalation on
+ * noise, and a completion nobody observed clears a streak on nothing. Appending
+ * neither leaves the path as vacuous as it was before this adapter existed, for
+ * that call.
+ *
+ * A POST EVENT ON THIS HARNESS IS NOT EVIDENCE THE TOOL RAN, which APRV-415's
+ * probe established and which changes what the missing-result case may conclude.
+ * `post_tool_call` fired 29ms after an exit-2 deny, and it fired again after the
+ * armed hang was refused at the 300s cap: Hermes reports the end of its own
+ * dispatch, not the end of an execution. So an envelope this reader cannot read
+ * is UNREADABLE rather than complete. The event name is Hermes saying its
+ * `post_tool_call` code path ran and nothing more, and crediting a completion on
+ * that alone would clear a failure streak (amended SPEC.md §10.2) on a call that
+ * may have been blocked. A blocked call usually has no `execution.started` to
+ * close, because the pre half appended nothing; the case this protects is the one
+ * where the pre half ALLOWED and something later in Hermes's own executor —
+ * `approvals.mode`, a guardrail, a tool-scope check — stopped the call anyway.
+ */
+function readHermesReportedOutcome(input) {
+    // A shell result arrives as an object on this harness (`tool_input` is an
+    // object throughout its contract), so the generic object reader is the right
+    // shape; a string result says nothing about success and says so below.
+    const response = input.toolResponse;
+    if (response === null) {
+        return {
+            ok: false,
+            detail: "the post_tool_call event carries no readable result, and on this harness a post event is not evidence the tool ran: it fires for a blocked call and after a refused timeout, so nothing here says the execution completed or failed",
+        };
+    }
+    if (response["interrupted"] === true || input.interrupted) {
+        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",
+        };
+    }
+    const exitCode = response["exit_code"] ?? response["exitCode"] ?? response["returncode"];
+    if (typeof exitCode === "number") {
+        return { ok: true, outcome: exitCode === 0 ? "completed" : "failed" };
+    }
+    const errorText = response["error"];
+    if (response["error"] === true ||
+        response["status"] === "error" ||
+        (typeof errorText === "string" && errorText.length > 0)) {
+        return { ok: true, outcome: "failed" };
+    }
+    // A result object the harness DID attach, naming neither an exit code nor an
+    // error: read as a completion, which is the generic reader's own precedent. The
+    // residual is stated rather than hidden — if a blocked call turns out to carry a
+    // result object of this shape, this line credits a completion that did not
+    // happen, and the repair is one more key here once a capture names it.
+    return { ok: true, outcome: "completed" };
+}
 function readReportedOutcome(input, adapter) {
     if (adapter.kind === "codex")
         return readCodexReportedOutcome(input);
+    if (adapter.kind === "hermes") {
+        if (input.hookEventName !== HERMES_POST_TOOL_EVENT) {
+            return {
+                ok: false,
+                detail: `hook_event_name is ${input.hookEventName === null ? "absent" : JSON.stringify(input.hookEventName)}, which is not the event this adapter reports an outcome for (${HERMES_POST_TOOL_EVENT})`,
+            };
+        }
+        return readHermesReportedOutcome(input);
+    }
+    if (adapter.kind === "muse") {
+        if (input.hookEventName !== "PostToolUse") {
+            return {
+                ok: false,
+                detail: `hook_event_name is ${input.hookEventName === null ? "absent" : JSON.stringify(input.hookEventName)}, which is not the event this adapter reports an outcome for (PostToolUse)`,
+            };
+        }
+        return readMuseReportedOutcome(input);
+    }
     const event = input.hookEventName;
     if (event !== "PostToolUse" && event !== "PostToolUseFailure") {
         return {
@@ -2132,7 +3923,14 @@ function readReportedOutcome(input, adapter) {
  * 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)) {
+    if (input.toolName !== adapter.shellTool &&
+        !adapter.fileTools.includes(input.toolName) &&
+        // APRV-347: a read tool MAY have had a start written for it (one outside
+        // the scope), so it belongs in this set. A read inside the scope wrote
+        // nothing, and the close below finds no start and says so in its own words.
+        !adapter.readTools.includes(input.toolName) &&
+        // APRV-445: a tool the rule table gated wrote a start like any other.
+        toolRuleOf(adapter, input)?.kind !== "gated") {
         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) {
@@ -2142,9 +3940,19 @@ function runPostToolUse(flags, streams, cwd, input, actor, adapter) {
         // `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");
     }
+    // APRV-311. The id the pre-execution half minted for this same call, derived
+    // here from the same two native fields it derived it from. It rides the
+    // unreadable arm so that the line naming a start nobody closed also names
+    // WHICH start: on Codex that arm is the only arm, and a diagnostic that
+    // cannot be joined to an `execution.started` leaves an operator grepping a
+    // log for a record they cannot identify. It is the correlation and nothing
+    // more — no outcome is read, inferred, or appended on this path.
+    const task = adapter.kind === "codex"
+        ? codexBinding(input, cwd).task
+        : `hook:${input.sessionId}:${input.toolUseId}`;
     const reading = readReportedOutcome(input, adapter);
     if (!reading.ok) {
-        return report(streams, "post-tool-unreadable-outcome", `${reading.detail}; nothing was appended`);
+        return report(streams, "post-tool-unreadable-outcome", `${reading.detail}; nothing was appended`, { task });
     }
     const { logPath, root } = hookScope(flags, cwd);
     if (!existsSync(logPath) && !existsSync(dirname(logPath))) {
@@ -2159,12 +3967,35 @@ function runPostToolUse(flags, streams, cwd, input, actor, adapter) {
         reportedBy: "post-tool-use",
     }, actor);
     if (!finished.ok) {
-        return report(streams, `post-tool-gate-refused:${finished.code}`, finished.message);
+        return report(streams, `post-tool-gate-refused:${finished.code}`, finished.message, { task });
     }
     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) {
+function describeToolCall(input, adapter, protectedPaths, cwd, readRoots = []) {
     if (adapter.kind === "codex" && input.toolName === "apply_patch") {
+        // APRV-363. The app-server's LEGACY `applyPatchApproval` carries its change
+        // as a MAP of path to change, inline on the request, and never as an
+        // `apply_patch` envelope. Rendering the map into an envelope so the parser
+        // below could read it would classify bytes this runtime wrote rather than
+        // bytes the server sent, which is the hazard APRV-362 exists for on the
+        // command side, so the map is classified as a map: by the paths it names,
+        // through the same protected-path rules every other file tool uses, with
+        // the change itself bound verbatim. It is described HERE rather than by the
+        // caller because one describer answers "what is this call", and a caller
+        // that could hand this module its own classes would be the party under
+        // oversight choosing its own scrutiny (SPEC §11.1 invariant 4).
+        //
+        // APRV-379 widened the material this branch reads and changed nothing about
+        // the reading. The ITEM-BASED API delivers the same change set as an ARRAY
+        // on an earlier `item/started` frame, and the bridge correlates that frame
+        // to the approval request by item id before calling in here. One describer
+        // still answers the question for both APIs, which is the point: two
+        // describers would be two answers to "what is this call", and the second
+        // one would be the one nobody reviewed.
+        const changes = codexFileChanges(input.toolInput);
+        if (changes !== null) {
+            return describeCodexFileChanges(changes, protectedPaths, cwd);
+        }
         const raw = readString(input.toolInput, "command");
         if (raw === null) {
             return { kind: "deny", code: "hook-io", detail: "apply_patch tool_input carries no command string" };
@@ -2192,17 +4023,55 @@ function describeToolCall(input, adapter, protectedPaths, cwd) {
                 detail: `${adapter.shellTool} tool_input carries no command string`,
             };
         }
+        // APRV-362. A call may state the argv its command renders, and the app-server
+        // bridge does, so the payload can name the words the kernel receives rather
+        // than a string somebody still has to parse. Two accounts of one call that
+        // disagree describe no call at all, so the disagreement is refused here
+        // instead of being resolved in favour of either. `codexArgv` accepts an
+        // argv only when the command splits to exactly it, which is why the only
+        // reachable outcomes are "absent", "agrees" and this.
+        if (adapter.kind === "codex" && codexArgvDisagrees(input.toolInput, raw)) {
+            return {
+                kind: "deny",
+                code: "hook-io",
+                detail: "the call states an argv that its own command string does not split to; a payload cannot bind two readings of one command, so nothing was classified",
+            };
+        }
+        // APRV-350: the PER-CALL working directory, where the harness sends one.
+        //
+        // Muse's `bash` carries `workdir`, and it is the directory the command will
+        // actually run in; the top-level `cwd` is the session root and the two can
+        // differ. The classifier resolves relative paths against this, so binding
+        // the session root instead would classify `rm -rf docs` against the wrong
+        // tree. Only an ABSOLUTE value is taken: a relative `workdir` is the
+        // harness describing a location this runtime cannot place, and a
+        // self-reported field may not talk its way into a narrower answer
+        // (SPEC §11.1), so the fallback is the value that was already trusted.
+        // `null` for every adapter that declares no key, which leaves both the
+        // payload and the classification EXACTLY as they were. That is not
+        // defensiveness: `input.cwd` and the hook's own `cwd` are different values,
+        // and a first version of this that used the envelope's `cwd` for every
+        // adapter re-classified Grok's commands against a directory that does not
+        // exist on disk and denied them all.
+        const perCallCwd = adapter.shellCwdKey === undefined
+            ? null
+            : readString(input.toolInput, adapter.shellCwdKey);
+        const shellCwd = perCallCwd !== null && isAbsolute(perCallCwd) ? perCallCwd : null;
         // 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 = adapter.bindToolName
             ? codexBinding(input, cwd).payload
-            : { command: raw, cwd: input.cwd };
+            : { command: raw, cwd: shellCwd ?? 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);
+        // Classified against the directory the command will RUN in, not the
+        // hook's own, so a relative path in the command resolves the way the shell
+        // will resolve it. For every adapter without a per-call working directory
+        // this is `input.cwd` or the hook's own cwd exactly as before.
+        const refined = classifyForHook(raw, protectedPaths, shellCwd ?? cwd, readRoots);
         const classified = refined.result;
         if (!classified.ok) {
             return {
@@ -2212,6 +4081,20 @@ function describeToolCall(input, adapter, protectedPaths, cwd) {
             };
         }
         const classes = classified.classes.filter((cls) => cls !== GATE_SELF_CLASS);
+        // APRV-445 refutation (B2, L10). The classifier matches protected paths by
+        // their SEGMENTS, and a relative word carries only the segments it was
+        // written with: `echo X >> .env` run in `$HERMES_HOME` names `.env`, not
+        // `.hermes/.env`, and classified as a workspace write. Where the harness
+        // states the per-call directory the command runs in, every relative word
+        // and every write target is ALSO judged resolved against it: a write that
+        // lands on an organ takes the organ's class, and a read that lands on a
+        // credential takes `account.credential`. It only ever adds a class.
+        if (shellCwd !== null) {
+            for (const cls of resolvedPathClasses(raw, classified.segments, shellCwd, protectedPaths)) {
+                if (!classes.includes(cls))
+                    classes.push(cls);
+            }
+        }
         if (adapter.kind === "codex") {
             // The pure shell classifier sees each segment independently. Preserve
             // Codex hook organs when an earlier simple `cd` changes the directory or
@@ -2293,6 +4176,52 @@ function describeToolCall(input, adapter, protectedPaths, cwd) {
             segments: classified.segments,
         };
     }
+    // APRV-445: the harness's own side-effecting tools, by name and arguments.
+    // The payload is the whole call, so a grant binds every argument.
+    const ruled = toolRuleOf(adapter, input);
+    if (ruled !== null) {
+        if (ruled.kind === "read")
+            return { kind: "allow", reason: ruled.reason };
+        return {
+            kind: "gated",
+            classes: [ruled.cls],
+            payload: { tool: input.toolName, input: input.toolInput },
+            headline: ruled.headline,
+            notes: [],
+        };
+    }
+    // APRV-347, above the file-tool branch because the two lists are disjoint and
+    // a read is the cheaper question to answer: a read inside the scope, or one
+    // naming no path at all, returns `null` here and takes the allow below.
+    if (adapter.readTools.includes(input.toolName)) {
+        // APRV-445 refutation (B2): a read tool naming a credential file is
+        // `account.credential` wherever the file sits, inside the read scope
+        // included, as the same read through the shell already was.
+        const credential = credentialReadGate(input.toolName, input.toolInput, cwd);
+        if (credential !== null) {
+            return {
+                kind: "gated",
+                classes: ["account.credential"],
+                payload: credential.payload,
+                headline: credential.summary,
+                notes: [],
+            };
+        }
+        const read = readToolGate(input.toolName, input.toolInput, readRoots, cwd);
+        if (read === null) {
+            return {
+                kind: "allow",
+                reason: `${input.toolName} is not a gated tool`,
+            };
+        }
+        return {
+            kind: "gated",
+            classes: [READ_OUT_OF_SCOPE_CLASS],
+            payload: read.payload,
+            headline: read.summary,
+            notes: [readScopeNote(read, readRoots)],
+        };
+    }
     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` };
@@ -2307,6 +4236,465 @@ function describeToolCall(input, adapter, protectedPaths, cwd) {
         notes: gated.protectedPath ? [fileTierNote(gated)] : [],
     };
 }
+/**
+ * The classes a shell command's PATHS take once they are resolved the way the
+ * shell and the filesystem will resolve them (APRV-445 refutation B2 and L10,
+ * recheck SF2 and L-e), for a harness that states the directory each call runs
+ * in.
+ *
+ * The classifier matches organs and credentials by path SEGMENTS of the words
+ * as written. A word written relative (`.env` run in `$HERMES_HOME`), through a
+ * variable (`$HERMES_HOME/.env`), after a `cd`, or through a symlinked parent
+ * (`h/.env` where `h -> .hermes`) carries none of the segments that matter. So
+ * each path a segment touches is also judged here:
+ *
+ * - WRITTEN paths are the redirect targets (heredocs included) and the
+ *   write-argument positions of the binaries whose writes are known (L-e):
+ *   never the binary, never a word that is merely an argument. A written path
+ *   resolving to an organ takes its class; one carrying a glob or a variable
+ *   this hook cannot expand is `policy.core` when it lands in one of the gate's
+ *   own directories ({@link gateRootKind}) or a pattern in it could name the
+ *   home or an organ (recheck 3); an unexpanded `$HERMES_HOME` in a written
+ *   path is `policy.core` wherever it is written from. A copy into a directory
+ *   writes `<dir>/<source name>`; an extraction writes into its directory.
+ * - READ paths (a read segment's arguments, `<` targets, a copy's sources) that
+ *   resolve to a credential take `account.credential`, and so does a directory
+ *   that holds credentials ({@link holdsCredentials}) handed to a binary that
+ *   reads directories recursively (`grep -r`, `rg`, `find`, `tar`, ...).
+ * - After a `cd` this hook cannot resolve, every later relative write is
+ *   `policy.core` and every later relative read `account.credential`.
+ * - `cd` moves the directory for the segments after it. Like the Codex arm, a
+ *   `cd` may or may not have run (`||`, a failed `cd`), so the directories
+ *   before and after it are both kept and every later path is judged from each.
+ * - Every path is resolved through `realpath` on its deepest existing ancestor,
+ *   so a symlinked parent or working directory is judged by where it lands.
+ * - `$HERMES_HOME` / `${HERMES_HOME}` expand to `APPROVAL_HERMES_HOME`, else
+ *   `HERMES_HOME`, from this hook process's environment; `~`, `$HOME` and
+ *   `${HOME}` to `HOME`. Under `approval serve` the process is the daemon, so a
+ *   hosted operator sets `APPROVAL_HERMES_HOME` there; without it, the
+ *   conservative rules above apply to the unexpanded spelling.
+ *
+ * What stays out of reach is listed in `docs/hermes-hook.md`: inline programs
+ * (`python -c`, which the classifier already refuses as opaque), `dd`/`install`
+ * (unclassified, so already denied), and a recursive search of an ANCESTOR of
+ * the home with a filename filter.
+ *
+ * It only ever adds classes.
+ */
+function resolvedPathClasses(raw, segments, cwd, protectedPaths, env = process.env) {
+    const found = [];
+    const add = (cls) => {
+        if (cls !== null && !found.includes(cls))
+            found.push(cls);
+    };
+    const shapes = commandSegmentShapes(raw) ?? [];
+    // Trusted as given: the operator sets it (under co-location, the control
+    // plane sets it from the tenant's home), and nothing the agent writes reaches
+    // this process's environment.
+    const hermesHome = env["APPROVAL_HERMES_HOME"] ?? env["HERMES_HOME"] ?? null;
+    const home = env["HOME"] ?? null;
+    /** The word with the variables this hook can know expanded. */
+    const expand = (word) => {
+        let text = word;
+        let hermesUnknown = false;
+        const hermesRef = /^\$(?:\{HERMES_HOME\}|HERMES_HOME)(?=\/|$)/u;
+        if (hermesRef.test(text)) {
+            if (hermesHome !== null && hermesHome.length > 0)
+                text = text.replace(hermesRef, hermesHome);
+            else
+                hermesUnknown = true;
+        }
+        const homeRef = /^(?:~|\$\{HOME\}|\$HOME)(?=\/|$)/u;
+        if (homeRef.test(text) && home !== null && home.length > 0)
+            text = text.replace(homeRef, home);
+        return { text, hermesUnknown, unresolved: hermesUnknown || /[$`]/u.test(text) };
+    };
+    // After a `cd` this hook cannot resolve (`cd $X`, `cd "$D"`, `cd -`), the
+    // directory every later relative path lands in is unknown (recheck 3, SF2).
+    let cwdUnknown = false;
+    let cwds = [canonicalPath(cwd)];
+    for (const [index, segment] of segments.entries()) {
+        const shape = shapes.length === segments.length
+            ? shapes[index]
+            : shapes.find((candidate) => candidate.text === segment.text);
+        if (shape === undefined)
+            continue;
+        const bin = shape.bin === null ? null : basename(shape.bin);
+        const operands = shape.args.filter((arg) => !arg.startsWith("-"));
+        if (bin === "cd" || bin === "pushd") {
+            const target = operands[0];
+            if (target === undefined) {
+                // A bare `cd` goes HOME; `cd -` and `pushd` with no operand go to a
+                // directory recorded earlier in a shell this hook never saw.
+                if (bin === "cd" && !shape.args.includes("-") && home !== null) {
+                    cwds = [...new Set([...cwds, canonicalPath(home)])];
+                }
+                else {
+                    cwdUnknown = true;
+                }
+            }
+            else {
+                const expanded = expand(target);
+                if (expanded.unresolved || hasGlobChars(expanded.text)) {
+                    cwdUnknown = true;
+                }
+                else {
+                    const next = cwds.map((from) => canonicalPath(resolvePathSegments(from, expanded.text)));
+                    cwds = [...new Set([...cwds, ...next])];
+                }
+            }
+            continue;
+        }
+        if (bin === null && shape.writes.length === 0 && shape.reads.length === 0)
+            continue;
+        const judgeWrite = (word) => {
+            const target = expand(word);
+            if (target.hermesUnknown) {
+                add("policy.core");
+                return;
+            }
+            if (!isAbsolute(target.text) && cwdUnknown) {
+                add("policy.core");
+                return;
+            }
+            const globbed = target.unresolved || hasGlobChars(target.text);
+            for (const from of cwds) {
+                const absoluteTarget = resolvePathSegments(from, target.text);
+                if (globbed) {
+                    // SF3a: a pattern in any component that could name the home, the
+                    // approval home or an organ is an organ write; a pattern written
+                    // into one of the gate's own directories (SF1b) may be any file
+                    // there. Anywhere else it is a workspace write.
+                    if (globCouldNameOrgan(absoluteTarget) || writesIntoGateRoot(canonicalPath(dirname(absoluteTarget)))) {
+                        add("policy.core");
+                    }
+                    continue;
+                }
+                add(protectedPathClass(canonicalPath(absoluteTarget), protectedPaths));
+            }
+        };
+        /** A copy or move INTO a directory writes `<dir>/<basename of source>`. */
+        const judgeWriteInto = (directory, sources) => {
+            for (const source of sources) {
+                const name = basename(expand(source).text);
+                if (name.length === 0 || name === "." || name === "..") {
+                    // `cp -r stuff/. dir`: the contents land in the directory itself.
+                    judgeExtractInto(directory);
+                    continue;
+                }
+                judgeWrite(join(directory, name));
+            }
+        };
+        /** An extraction or a contents-copy writes unknown names into `directory`. */
+        const judgeExtractInto = (directory) => {
+            const target = expand(directory);
+            if (target.hermesUnknown || (cwdUnknown && !isAbsolute(target.text))) {
+                add("policy.core");
+                return;
+            }
+            if (target.unresolved)
+                return;
+            for (const from of cwds) {
+                if (writesIntoGateRoot(canonicalPath(resolvePathSegments(from, target.text))))
+                    add("policy.core");
+            }
+        };
+        const judgeRead = (word, recursive) => {
+            const target = expand(word);
+            if (target.hermesUnknown) {
+                add("account.credential");
+                return;
+            }
+            if (!isAbsolute(target.text) && cwdUnknown) {
+                add("account.credential");
+                return;
+            }
+            if (target.unresolved)
+                return;
+            for (const from of cwds) {
+                const absoluteTarget = resolvePathSegments(from, target.text);
+                if (hasGlobChars(target.text)) {
+                    // SF3b: expand against the directory when it is known; otherwise a
+                    // pattern that could name a credential is read as one.
+                    const candidates = expandGlob(absoluteTarget);
+                    if (candidates === null) {
+                        if (globCouldNameCredential(absoluteTarget))
+                            add("account.credential");
+                    }
+                    else {
+                        for (const candidate of candidates) {
+                            if (isCredentialPath(canonicalPath(candidate)))
+                                add("account.credential");
+                        }
+                    }
+                    continue;
+                }
+                const resolved = canonicalPath(absoluteTarget);
+                if (isCredentialPath(resolved))
+                    add("account.credential");
+                else if (recursive && holdsCredentials(resolved))
+                    add("account.credential");
+            }
+        };
+        for (const target of shape.writes)
+            judgeWrite(target);
+        for (const source of shape.reads)
+            judgeRead(source, false);
+        if (bin === null)
+            continue;
+        // `-t DIR` / `--target-directory=DIR` names the destination up front.
+        const targetDirFlag = () => {
+            for (const [at, arg] of shape.args.entries()) {
+                if (arg === "-t")
+                    return shape.args[at + 1] ?? null;
+                if (arg.startsWith("--target-directory="))
+                    return arg.slice("--target-directory=".length);
+            }
+            return null;
+        };
+        if (WRITE_EVERY_OPERAND.has(bin)) {
+            for (const operand of operands)
+                judgeWrite(operand);
+        }
+        else if (WRITE_LAST_OPERAND.has(bin)) {
+            const targetDir = targetDirFlag();
+            const sources = targetDir === null ? operands.slice(0, -1) : operands.filter((operand) => operand !== targetDir);
+            const destination = targetDir ?? operands[operands.length - 1];
+            for (const source of sources)
+                judgeRead(source, true);
+            if (destination !== undefined) {
+                const expanded = expand(destination);
+                const intoDirectory = targetDir !== null ||
+                    destination.endsWith("/") ||
+                    (!expanded.unresolved &&
+                        cwds.some((from) => isDirectoryPath(canonicalPath(resolvePathSegments(from, expanded.text)))));
+                if (intoDirectory)
+                    judgeWriteInto(destination, sources);
+                else
+                    judgeWrite(destination);
+            }
+        }
+        else if (WRITE_AFTER_FIRST_OPERAND.has(bin)) {
+            for (const operand of operands.slice(1))
+                judgeWrite(operand);
+        }
+        else if (bin === "sed" && shape.args.some((arg) => arg === "--in-place" || /^-[a-zA-Z]*i/u.test(arg))) {
+            const scripted = shape.args.some((arg) => arg === "-e" || arg === "-f");
+            for (const operand of scripted ? operands : operands.slice(1))
+                judgeWrite(operand);
+        }
+        else if (bin === "dd") {
+            for (const arg of shape.args) {
+                if (arg.startsWith("of="))
+                    judgeWrite(arg.slice(3));
+                if (arg.startsWith("if="))
+                    judgeRead(arg.slice(3), false);
+            }
+        }
+        else if (bin === "tar" && isTarExtract(shape.args)) {
+            // Lows: an extraction writes the archive's names into `-C DIR` or the
+            // working directory.
+            judgeExtractInto(flagValue(shape.args, "-C", "--directory") ?? ".");
+        }
+        else if (bin === "unzip") {
+            judgeExtractInto(flagValue(shape.args, "-d", null) ?? ".");
+        }
+        if (segment.class.startsWith("read.") || RECURSIVE_READERS.has(bin)) {
+            for (const operand of operands)
+                judgeRead(operand, RECURSIVE_READERS.has(bin));
+        }
+    }
+    return found;
+}
+/** `*`, `?` or `[` in a path word. */
+function hasGlobChars(text) {
+    return /[*?[]/u.test(text);
+}
+/** A shell glob component as an anchored regular expression. */
+function globRegex(component) {
+    let source = "";
+    for (const char of component) {
+        if (char === "*")
+            source += ".*";
+        else if (char === "?")
+            source += ".";
+        else if (char === "[" || char === "]")
+            source += char;
+        else
+            source += char.replace(/[.+^${}()|\\]/gu, "\\$&");
+    }
+    try {
+        return new RegExp(`^${source}$`, "u");
+    }
+    catch {
+        return /^.*$/u;
+    }
+}
+/** Names a credential file goes by, for a pattern to be tested against. */
+const CREDENTIAL_NAMES = [".env", ".env.local", "auth.json", "env", "vault.enc", "keys"];
+/** Names an organ goes by, beyond the credentials. */
+const ORGAN_NAMES = [
+    ...CREDENTIAL_NAMES,
+    "config.yaml",
+    "config.yml",
+    "shell-hooks-allowlist.json",
+    "shell-hooks-allowlist.json.lock",
+    "agent-hooks",
+    "approval",
+    "scripts",
+];
+/** Could some component of `path`'s pattern name the home or the approval home? */
+function globCouldNameGateHome(path) {
+    return path
+        .split(/[/\\]+/u)
+        .some((component) => hasGlobChars(component) && [".hermes", ".approval"].some((name) => globRegex(component).test(name)));
+}
+/** SF3a: a written pattern that could land on an organ. */
+function globCouldNameOrgan(path) {
+    if (globCouldNameGateHome(path))
+        return true;
+    const last = basename(path);
+    if (!hasGlobChars(last))
+        return false;
+    const pattern = globRegex(last);
+    const parent = dirname(path);
+    const parentIsHome = parent.split(/[/\\]+/u).some((segment) => segment === ".hermes" || segment === ".approval") ||
+        hasGlobChars(parent);
+    return parentIsHome && ORGAN_NAMES.some((name) => pattern.test(name));
+}
+/** SF3b: a read pattern whose directory is unknown, that could name a credential. */
+function globCouldNameCredential(path) {
+    const last = basename(path);
+    if (!hasGlobChars(last))
+        return globCouldNameGateHome(path);
+    const pattern = globRegex(last);
+    return CREDENTIAL_NAMES.some((name) => pattern.test(name)) || globCouldNameGateHome(path);
+}
+/** The entries a final-component glob matches, or `null` when the directory is unknown. */
+function expandGlob(path) {
+    const parent = dirname(path);
+    if (hasGlobChars(parent))
+        return null;
+    try {
+        const pattern = globRegex(basename(path));
+        return readdirSync(canonicalPath(parent))
+            .filter((name) => pattern.test(name))
+            .map((name) => join(parent, name));
+    }
+    catch {
+        return null;
+    }
+}
+function isDirectoryPath(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The gate's own directories (recheck 3, SF1): a Hermes home (or profile home)
+ * root, an approval home, a home's `approval/`, and its `scripts/`. Everything
+ * else under a home (`workspace/`, `skills/`, `memories/`, `sessions/`) is
+ * ordinary work, which matters because a hosted image runs ALL agent work under
+ * `$HERMES_HOME`.
+ */
+function gateRootKind(directory) {
+    const segments = directory.split(/[/\\]+/u).filter((segment) => segment.length > 0);
+    const last = segments[segments.length - 1];
+    const isHome = (at) => segments[at] === ".hermes" ||
+        (segments[at - 2] === ".hermes" && segments[at - 1] === "profiles" && segments[at] !== undefined);
+    if (last === undefined)
+        return null;
+    if (isHome(segments.length - 1))
+        return "home";
+    if (last === ".approval")
+        return "approval-home";
+    if (last === "approval" && isHome(segments.length - 2))
+        return "home-approval";
+    if (last === "scripts" && isHome(segments.length - 2))
+        return "scripts";
+    return null;
+}
+/** A glob or an unknown name written here may be an organ (SF1b). */
+function writesIntoGateRoot(directory) {
+    return gateRootKind(directory) !== null;
+}
+/**
+ * A directory a recursive read of which reads credentials (SF1a): the home
+ * root, the approval home, a home's `approval/`, and any directory under a home
+ * that directly holds a credential file.
+ */
+function holdsCredentials(directory) {
+    if (!isDirectoryPath(directory))
+        return false;
+    const kind = gateRootKind(directory);
+    if (kind === "home" || kind === "approval-home" || kind === "home-approval")
+        return true;
+    if (!directory.split(/[/\\]+/u).some((segment) => segment === ".hermes" || segment === ".approval"))
+        return false;
+    return CREDENTIAL_FILE_NAMES.some((name) => existsSync(join(directory, name)));
+}
+const CREDENTIAL_FILE_NAMES = [
+    ".env",
+    "auth.json",
+    "config.yaml",
+    "config.yml",
+    "shell-hooks-allowlist.json",
+    "shell-hooks-allowlist.json.lock",
+];
+function isTarExtract(args) {
+    const first = args[0] ?? "";
+    return args.some((arg) => arg === "--extract" || arg === "--get" || /^-[a-zA-Z]*x/u.test(arg)) ||
+        (!first.startsWith("-") && first.includes("x"));
+}
+function flagValue(args, short, long) {
+    for (const [at, arg] of args.entries()) {
+        if (arg === short)
+            return args[at + 1] ?? null;
+        if (arg.startsWith(short) && arg.length > short.length && !arg.startsWith("--"))
+            return arg.slice(short.length);
+        if (long !== null && arg.startsWith(`${long}=`))
+            return arg.slice(long.length + 1);
+        if (long !== null && arg === long)
+            return args[at + 1] ?? null;
+    }
+    return null;
+}
+/** Binaries every operand of which is a path they create, change or remove. */
+const WRITE_EVERY_OPERAND = new Set([
+    "touch", "truncate", "mkdir", "rm", "rmdir", "shred", "tee", "unlink",
+]);
+/** Binaries whose LAST operand is the destination and the rest are sources. */
+const WRITE_LAST_OPERAND = new Set(["cp", "mv", "ln", "install", "rsync"]);
+/** Binaries whose first operand is a mode or owner and the rest are paths. */
+const WRITE_AFTER_FIRST_OPERAND = new Set(["chmod", "chown", "chgrp"]);
+/** Readers that walk a directory they are handed. */
+const RECURSIVE_READERS = new Set([
+    "grep", "egrep", "fgrep", "rg", "ag", "ack", "find", "tar", "zip", "du", "tree",
+]);
+/**
+ * `path` resolved through the realpath of its deepest existing ancestor, so a
+ * symlinked parent is judged by where it lands and a path that does not exist
+ * yet is judged by where it would be created (APRV-445 recheck SF2(e)).
+ */
+function canonicalPath(path) {
+    let current = path;
+    const tail = [];
+    for (;;) {
+        try {
+            return resolvePathSegments(realpathSync(current), ...tail.reverse());
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return resolvePathSegments(path);
+            tail.push(basename(current));
+            current = parent;
+        }
+    }
+}
 /** The environment variable that turns the sandbox requirement on (APRV-193). */
 export const REQUIRE_SANDBOX_ENV = "APPROVAL_HOOK_REQUIRE_SANDBOX";
 /**
@@ -2439,7 +4827,11 @@ decidedOn) {
     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);
+    const described = describeToolCall(input, adapter, protectedPaths, cwd, 
+    // APRV-347. The window suspends the POLICY, not the classification: a read
+    // outside the scope is described as one here too, so the bypass RECORD says
+    // what was actually authorized rather than calling it an ordinary read.
+    resolveReadRoots(cwd, policyRootOf(load, scope.root), load.ok ? load.policy.read_scope?.roots : undefined));
     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);
     }
@@ -2459,6 +4851,15 @@ decidedOn) {
         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) {
+        // APRV-354, above the human-only check here for the same reason it sits
+        // above it on the ordinary path. A window suspends what the policy DECIDES;
+        // it cannot supply a decision the policy never made. A launch the policy
+        // names no rule for is not a class the window is holding open — it is a
+        // class nobody has opted into — so the window does not reach it either.
+        const unruled = classes.find((cls) => harnessLaunchNeedsRule(cls, resolvePolicy(load, cls)));
+        if (unruled !== undefined) {
+            return deny(streams, "hook-harness-launch-unruled", `${harnessLaunchUnruledRefusal(unruled, "this command may not run under an agent")} An open window does not reach it: a window suspends what the policy decides, and this is a class the policy has not spoken about at all.`, adapter.kind);
+        }
         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);
@@ -2497,8 +4898,13 @@ decidedOn) {
     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, codexCommand);
 }
-function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
-    const configurationError = (message) => adapter.kind === "codex" ? deny(streams, "hook-io", message, adapter.kind) : usageError(streams, message);
+function runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
+    // Codex and (APRV-445) Hermes answer a misconfigured entry with a verdict:
+    // on both a usage error's empty stdout is a harness that runs the call, and
+    // on Hermes a non-zero exit with an empty stdout is an allow outright.
+    const configurationError = (message) => adapter.kind === "codex" || adapter.kind === "hermes"
+        ? deny(streams, "hook-io", message, adapter.kind)
+        : usageError(streams, message);
     const parsed = parseFlags(argv, {
         ...COMMON_FLAGS,
         ...POLICY_FLAGS,
@@ -2507,11 +4913,31 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         "--timeout": "string",
         "--interval": "string",
         "--retry-grace": "string",
+        "--harness-cap": "string",
     });
     if (!parsed.ok)
         return configurationError(parsed.message);
     if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
-        streams.out(`${HOOK_HELP}\n`);
+        // APRV-243. Grok's help carries the `.grok/hooks/*.json` the human commits,
+        // because that file's `timeout` is load-bearing: it must exceed `--timeout`
+        // or Grok abandons the hook mid-wait and, failing open, runs the command.
+        // Muse gets its own for the same reason and one more: its `.muse/hooks.json`
+        // shape is not Claude's file under a different name, and an operator who
+        // guessed would get "Hooks: 0 runnable" and a session that looks gated.
+        // Hermes gets its own for a third reason on top of those two (APRV-398):
+        // the file the human commits is YAML, it is not in the repository at all
+        // (`$HERMES_HOME/config.yaml`), and the entry carries the one key that
+        // decides whether this adapter is a gate or a backstop — `fail_closed`. A
+        // reader who copied a JSON block from another harness's help would install
+        // nothing.
+        const harnessHelp = adapter.kind === "grok"
+            ? HOOK_GROK_HELP
+            : adapter.kind === "muse"
+                ? HOOK_MUSE_HELP
+                : adapter.kind === "hermes"
+                    ? HOOK_HERMES_HELP
+                    : HOOK_HELP;
+        streams.out(`${harnessHelp}\n`);
         return EXIT_OK;
     }
     const extra = parsed.positionals[0];
@@ -2541,16 +4967,94 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     if (graceMs === null) {
         return configurationError(`--retry-grace expects a duration like 5m, 30s, 1ms, got ${JSON.stringify(graceText)}`);
     }
-    const parsedInput = parseHookInput(readStdin());
+    // APRV-423. The ceiling this process runs under, which the hook cannot
+    // discover for itself: the harness spawns it and tells it nothing. The
+    // OPERATOR states the entry timeout they configured, and the adapter
+    // contributes the harness's own documented maximum where its contract has
+    // one. The smaller wins, because a stated cap above a contractual ceiling is
+    // a statement the harness will not honour, and a cap may only ever shorten
+    // the window (SPEC.md §11.1 invariant 4).
+    const capText = stringFlag(parsed.flags, "--harness-cap");
+    const statedCapMs = capText === null ? null : parseDuration(capText);
+    if (capText !== null && statedCapMs === null) {
+        return configurationError(`--harness-cap expects a duration like 300s, 4m, got ${JSON.stringify(capText)}`);
+    }
+    // Second review pass. A stated cap is clamped to the contractual ceiling
+    // (Hermes will not honour an entry above 300 s however it is written); an
+    // absent flag takes the harness's DEFAULT bound where the adapter documents
+    // one, and only then falls back to the ceiling. The default is the stricter
+    // number on purpose: an operator who has said nothing is assumed to run the
+    // harness as shipped, and a runtime that assumed the ceiling instead would
+    // assert a deadline the harness will not keep (APRV-410 with a fictional
+    // T+240 s, which is exactly what the first pass did on a default Hermes).
+    const capMs = effectiveHarnessCapMs(adapter, statedCapMs);
+    // APRV-427 review: charged for the time the call spent before this line,
+    // using the remainder the embedding caller admitted it on, unchanged. See
+    // HookWaitSeam.remainingCapMs.
+    const remainingCapMs = waitSeam?.remainingCapMs;
+    const harnessCapMs = capMs === null || remainingCapMs === undefined
+        ? capMs
+        : Math.max(0, Math.min(capMs, remainingCapMs));
+    const harnessCapStated = statedCapMs !== null;
+    const parsedInput = parseHookInput(readStdin(), adapter.camelCaseEnvelope === true);
     if (!parsedInput.ok)
         return deny(streams, "hook-io", parsedInput.detail, adapter.kind);
     const input = parsedInput.input;
     if (adapter.kind === "codex") {
         const checked = checkCodexHookInput(input, cwd);
-        if (!checked.ok)
-            return deny(streams, "hook-io", checked.detail, adapter.kind);
+        if (!checked.ok) {
+            // APRV-311. WHICH PHASE the malformed event belongs to decides which
+            // vocabulary refuses it, and until now both took the pre-execution one.
+            // A `PostToolUse` event naming an unsupported tool, or carrying an id
+            // this adapter will not accept, printed
+            // `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny"}}`
+            // at exit 0: a permission decision about a call that has already run, in
+            // the same words the pre-execution refusal uses, so nothing downstream
+            // could tell the two apart. Nothing was ever going to be authorized here.
+            //
+            // The strict answer on this side is the one the rest of the post path
+            // already gives: say so on stderr at the exit code that makes the line
+            // visible, append nothing, and print no verdict. The event name is read
+            // off the raw input rather than off the check, because the check is what
+            // just failed.
+            return input.hookEventName === CODEX_POST_TOOL_EVENT
+                ? report(streams, "post-tool-io", `${checked.detail}; nothing was appended, so the start this event would have closed is still open`)
+                : deny(streams, "hook-io", checked.detail, adapter.kind);
+        }
     }
     const codexCommand = adapter.kind === "codex" ? codexBinding(input, cwd).payload.command : undefined;
+    // APRV-350. The contributor guard runs BEFORE the event dispatch, the policy
+    // and everything else, because it is not a question about the action: a
+    // Contributor-tier session discloses every byte it reads, so there is nothing
+    // for a policy to authorize. Refusing first also means no unparseable payload,
+    // no missing log and no classifier quirk can route around it.
+    //
+    // On a POST event it refuses in the post vocabulary and prints no verdict:
+    // Muse rejects a permission field on a post event, and a rejected hook is a
+    // FAILED hook, which fails open. There is nothing to block after the fact
+    // anyway; the line exists so the disclosure is on a stream somebody reads.
+    if (adapter.contributorModelGuard === true) {
+        const refusal = contributorModelRefusal(input.model);
+        if (refusal !== null) {
+            const postEvent = isPostToolEvent(adapter, input.hookEventName);
+            return postEvent
+                ? report(streams, MUSE_CONTRIBUTOR_REFUSAL, `${refusal} Nothing was appended.`)
+                : deny(streams, MUSE_CONTRIBUTOR_REFUSAL, refusal, adapter.kind);
+        }
+    }
+    // APRV-350. The harness's own bookkeeping tool, answered and never gated.
+    // Muse fires both events for `submit_reminder_decision` continuously — 100 of
+    // the 139 events in the live capture — and it records a self-assessment and
+    // touches nothing. It is answered with an explicit allow rather than left to
+    // fall through, so the verdict is one dialect and nothing else, which is the
+    // only shape this harness parses.
+    if (adapter.passThroughTools?.includes(input.toolName) === true) {
+        const passPostEvent = isPostToolEvent(adapter, input.hookEventName);
+        if (passPostEvent) {
+            return report(streams, "post-tool-not-gated", `${input.toolName} is the harness's own bookkeeping tool, so no execution.started was ever written for it`);
+        }
+        return allow(streams, `${input.toolName} is ${adapter.kind}'s own bookkeeping tool: it records the session's self-assessment and touches nothing outside the session`, adapter.kind);
+    }
     // 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
@@ -2561,9 +5065,7 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // 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.
-    const postToolEvent = adapter.kind === "codex"
-        ? input.hookEventName === CODEX_POST_TOOL_EVENT
-        : input.hookEventName !== null && POST_TOOL_EVENTS.includes(input.hookEventName);
+    const postToolEvent = isPostToolEvent(adapter, input.hookEventName);
     if (postToolEvent) {
         // 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
@@ -2571,11 +5073,27 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         // 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.
+        //
+        // APRV-243. Grok Build reads exit 2 as DENY, full stop, so the visibility
+        // exit this path uses everywhere else would be a permission decision about
+        // a tool call that has already run. On this one harness the post-execution
+        // path therefore always exits 0. The machine-readable line still goes to
+        // stderr; whether Grok shows it is Grok's business, and losing a debug line
+        // is a smaller harm than emitting a verdict the protocol will act on.
+        //
+        // APRV-398. Hermes joins Grok on that rule, and for the same reason read off
+        // its own contract: Hermes documents exit 2 as BLOCKING, so a visibility
+        // exit here would be a block aimed at a tool call that has already run.
+        // This adapter's whole stance on this harness is that the exit status
+        // carries no verdict (see `HERMES_DENY_EXIT`), and that has to hold on both
+        // halves or it holds nowhere. The machine-readable line still goes to
+        // stderr, and whether Hermes shows it is Hermes's business.
+        const settle = (code) => adapter.kind === "grok" || adapter.kind === "hermes" ? EXIT_OK : code;
         try {
-            return runPostToolUse(parsed.flags, streams, cwd, input, actor, adapter);
+            return settle(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`);
+            return settle(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`));
         }
     }
     // Codex 0.152.1 can execute Bash in a per-call working directory that is
@@ -2585,10 +5103,72 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // harness executes. Refuse before the open-window, gate-self, carry, or
     // registration paths; none of those can supply the missing directory fact.
     if (adapter.kind === "codex" && input.toolName === "Bash") {
-        return deny(streams, "hook-io", "Codex Bash is disabled because the native hook contract does not expose the effective per-call working directory; no policy or open window can authorize bytes the hook cannot bind", adapter.kind);
+        return deny(streams, "hook-unsupported-execution-context", "Codex Bash is disabled because the native hook contract does not expose the effective per-call working directory; no policy or open window can authorize bytes the hook cannot bind", adapter.kind);
+    }
+    // APRV-398, and placed exactly where the Codex refusal above is placed, for
+    // exactly its reason: before the open window, the gate-self path, the carry
+    // and the registration, because none of those can supply a fact the call does
+    // not carry. Hermes's `execute_code` takes a `code` string and nothing else —
+    // no path, no argv, no working directory — so there is nothing for the
+    // classifier to read and nothing a payload could bind. A verdict over
+    // `{code}` would authorize a program this runtime never parsed.
+    //
+    // It is refused rather than classified `hook-opaque` because the repair
+    // differs: an opaque command line can be rewritten, and there is no spelling
+    // of an `execute_code` call that this hook could answer differently. Nothing
+    // appends on this path and no gate lifecycle opens. An OPEN WINDOW does not
+    // reach it either, which is the strict reading a window deserves here: a
+    // window suspends the policy, and this refusal is not a policy question.
+    if (adapter.kind === "hermes" && input.toolName === HERMES_EXECUTE_CODE_TOOL) {
+        return deny(streams, HERMES_EXECUTE_CODE_REFUSAL, `Hermes ${HERMES_EXECUTE_CODE_TOOL} is refused because the call carries a program and nothing else: no path, no argv and no working directory, so no class can be resolved and no payload can bind what it would do. Run the work through the \`${adapter.shellTool}\` tool, where the words are visible to the classifier, or through \`approval run\` with a granted token. No policy or open window authorizes bytes the hook cannot read`, adapter.kind);
+    }
+    // APRV-415, and placed here for the reason the two refusals above are: before
+    // the open window, the gate-self path, the carry and the registration, because
+    // none of those can supply the directory a Hermes call leaves out. The live
+    // probe established that this harness reports NO effective directory for a
+    // call that does not state one — see {@link hermesUnboundDirectory} — so the
+    // refusal is the Codex `Bash` refusal one harness along, narrowed to the calls
+    // that actually withhold the fact.
+    if (adapter.kind === "hermes") {
+        const unbound = hermesUnboundDirectory(input, adapter);
+        if (unbound !== null) {
+            return deny(streams, "hook-unsupported-execution-context", unbound, adapter.kind);
+        }
+    }
+    // APRV-445: a tool the adapter's own rule table gates goes on to the gated
+    // path below; one it reads is allowed here, with no policy load, exactly as
+    // an in-scope read is.
+    const ruledEarly = toolRuleOf(adapter, input);
+    if (ruledEarly?.kind === "read") {
+        return allow(streams, ruledEarly.reason, adapter.kind, codexCommand);
     }
-    if (input.toolName !== adapter.shellTool && !adapter.fileTools.includes(input.toolName)) {
-        return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+    if (ruledEarly === null &&
+        input.toolName !== adapter.shellTool &&
+        !adapter.fileTools.includes(input.toolName)) {
+        if (!adapter.readTools.includes(input.toolName)) {
+            return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+        }
+        // APRV-347, and the placement is the whole of its cost. A read tool call is
+        // the most frequent event a session produces, and before this task it was
+        // answered here with no policy load, no verified read of the log and no
+        // window lookup. Everything below this line is expensive, so the reads that
+        // do not need it must not pay for it.
+        //
+        // The short-circuit is sound because `read_scope` is ADDITIVE: it can only
+        // widen the roots, so a target already inside the BUILT-IN roots is inside
+        // the effective ones whatever the policy says, and the policy need not be
+        // read to know it. A target outside them falls through, the policy is
+        // loaded below, and `describeToolCall` asks again with the widened set —
+        // which is where a policy-declared root actually takes effect.
+        //
+        // The cost of the fast path is a handful of `realpath` calls and no process
+        // spawn, provided the hook is configured with `--dir` as the docs show
+        // (otherwise `hookScope` runs `git rev-parse` to find the primary).
+        const early = hookScope(parsed.flags, cwd);
+        if (credentialReadGate(input.toolName, input.toolInput, cwd) === null &&
+            readToolGate(input.toolName, input.toolInput, resolveReadRoots(cwd, early.root), cwd) === null) {
+            return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+        }
     }
     // 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:
@@ -2625,6 +5205,49 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         // verdict and the record are one read of the log.
         looked.records === null ? null : { records: looked.records, head: looked.head });
     }
+    return renderVerdict(streams, adapter, codexCommand, decideHarnessCall({
+        streams,
+        input,
+        adapter,
+        cwd,
+        logPath,
+        root,
+        options,
+        actor,
+        timeoutMs,
+        intervalMs,
+        graceMs,
+        harnessCapMs,
+        harnessCapStated,
+        // The ceiling before the time in line was charged, for the refusal's
+        // wording only: the charged number is the one everything is judged by.
+        ...(harnessCapMs !== capMs && capMs !== null ? { harnessCapCeilingMs: capMs } : {}),
+        codexCommand,
+        windowRecords: looked.records,
+        waitSeam,
+    }));
+}
+/**
+ * Classify, resolve, gate and wait: one harness tool call, from the event to a
+ * verdict (APRV-361).
+ *
+ * Extracted from the hook's own verb so a SECOND caller can reach a decision
+ * through exactly this sequence. `cli/codex-bridge.ts` answers Codex's
+ * app-server approval requests over JSON-RPC rather than on stdout, and the
+ * thing it must not do is re-implement any of what is below: the human-only
+ * refusal, the unruled `harness.launch.*` refusal, the sandbox requirement, the
+ * loop floor, the unattended guard, the autonomous charge, and the register,
+ * request and wait that follow. Two implementations of that sequence would be
+ * two gates, and the second one would be the one nobody reviewed.
+ *
+ * It returns a verdict and prints none. `streams.err` still carries the
+ * progress and withdrawal lines, which are a report rather than a decision.
+ */
+export function decideHarnessCall(decide) {
+    const { streams, input, adapter, cwd, logPath, root, options, actor, timeoutMs, intervalMs, graceMs, codexCommand, windowRecords, } = decide;
+    const harnessCapMs = decide.harnessCapMs ?? null;
+    const harnessCapStated = decide.harnessCapStated ?? false;
+    const harnessCapCeilingMs = decide.harnessCapCeilingMs ?? null;
     // 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
@@ -2637,25 +5260,36 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         ? { 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);
+        return {
+            permission: "deny",
+            code: "hook-policy-unavailable",
+            detail: `${load.code}: ${load.message}; every class resolves to manual and the hook cannot verify a decision`,
+        };
     }
     const protectedPaths = load.policy.protected_paths ?? [];
+    // APRV-347. Resolved from the LOADED policy's own directory, so the scope is
+    // anchored to the gate a decision will be recorded in, and widened by
+    // `read_scope.roots` if that policy declares any.
+    const readRoots = resolveReadRoots(cwd, policyRootOf(load, root), load.policy.read_scope?.roots);
     // 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);
+    const described = describeToolCall(input, adapter, protectedPaths, cwd, readRoots);
     if (described.kind === "deny") {
-        return deny(streams, described.code, described.detail, adapter.kind);
+        return { permission: "deny", code: described.code, detail: described.detail };
     }
     if (described.kind === "allow") {
-        return allow(streams, described.reason, adapter.kind, codexCommand);
+        return { permission: "allow", reason: described.reason };
     }
     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, codexCommand);
+        return {
+            permission: "allow",
+            reason: "the approval CLI is the gate itself and is not gated by it",
+        };
     }
     // Every path from here needs the log, the fast paths included (APRV-139):
     // attestation and loop-escalation are facts about the log, so the
@@ -2664,7 +5298,11 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // 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);
+        return {
+            permission: "deny",
+            code: "hook-log-unreachable",
+            detail: `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`,
+        };
     }
     // Minted once, here, and carried into `gateAndWait`: the loop-escalation
     // check below and any registration that follows must name the same task.
@@ -2672,6 +5310,7 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         ? codexBinding(input, cwd).task
         : `hook:${input.sessionId}:${input.toolUseId ?? randomBytes(8).toString("hex")}`;
     const run = {
+        waitSeam: decide.waitSeam ?? null,
         logPath,
         options,
         actor,
@@ -2679,6 +5318,13 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         intervalMs,
         graceMs,
         ttlMs: load.durations.approvalTtlMs,
+        harnessCapMs,
+        harnessCapStated,
+        harnessCapCeilingMs,
+        harnessCapRepair: adapter.capRepair ?? null,
+        waitMs: harnessCapMs === null
+            ? timeoutMs
+            : Math.max(0, Math.min(timeoutMs, harnessCapMs - HARNESS_CAP_MARGIN_MS)),
         harness: adapter.kind,
         originApp: adapter.originApp,
         ...(codexCommand === undefined ? {} : { codexCommand }),
@@ -2690,7 +5336,26 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         // state.
         channels: Object.keys(load.policy.channels ?? {}).sort(),
     };
-    const autonomies = classes.map((cls) => resolvePolicy(load, cls).autonomy);
+    const resolutions = classes.map((cls) => resolvePolicy(load, cls));
+    const autonomies = resolutions.map((resolution) => resolution.autonomy);
+    // APRV-354, and ABOVE the human-only deny because it is the narrower
+    // statement: this class is not merely reserved, it is one the policy has not
+    // spoken about at all, and the repair is a line rather than a person.
+    //
+    // A `harness.launch.*` class resolves only under a rule an operator wrote. A
+    // policy naming neither the family nor the member refuses the launch instead
+    // of falling to `defaults.autonomy`, which keeps arrival exactly as strict as
+    // it was before the family existed (`hook-unclassified`, refused) until
+    // somebody opts in. See `harnessLaunchNeedsRule` for why the family gets this
+    // and no other class does.
+    const unruled = classes.find((cls, index) => harnessLaunchNeedsRule(cls, resolutions[index]));
+    if (unruled !== undefined) {
+        return {
+            permission: "deny",
+            code: "hook-harness-launch-unruled",
+            detail: harnessLaunchUnruledRefusal(unruled, "this command may not run under an agent"),
+        };
+    }
     // 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
@@ -2706,7 +5371,11 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // 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);
+        return {
+            permission: "deny",
+            code: "hook-class-human-only",
+            detail: `${humanOnlyRefusal(reserved, "this command may not run under an agent")} The gate's own code for this fact is \`class-human-only\`.`,
+        };
     }
     // 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
@@ -2714,7 +5383,7 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // 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);
+        return { permission: "deny", code: "hook-sandbox-required", detail: unsandboxed };
     }
     // 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
@@ -2729,9 +5398,9 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // 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);
+    const floored = harnessFloor(logPath, task, actor, windowRecords);
     if (!floored.ok)
-        return deny(streams, "hook-io", floored.detail, adapter.kind);
+        return { permission: "deny", code: "hook-io", detail: floored.detail };
     /**
      * The streak the log shows, before the read carve-out (APRV-297).
      *
@@ -2780,11 +5449,39 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     /** 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);
+        const refused = unattendedGuard(logPath, load.source.path, task, windowRecords);
+        if (refused !== null) {
+            return { permission: "deny", code: refused.code, detail: refused.detail };
+        }
     }
     if (floor === null && autonomies.every((autonomy) => autonomy === "autonomous")) {
+        // APRV-410. The sweep that takes back this actor's abandoned questions used
+        // to live only in `gateHarnessCall`, which an autonomous command never
+        // reaches — so a session whose retry classified autonomously left its
+        // expired question standing until the TTL, and a human's tap on it six
+        // minutes past the grace was recorded as a grant nobody held (log seq
+        // 64473, 2026-09-20). The withdrawal has to be made by the REQUESTER, which
+        // is this actor: `withdraw` refuses a `system:` actor in as many words, and
+        // the event schema's cross-rule binds a `system:` withdrawal to
+        // `policy-drift` alone (APRV-235), so the daemon is not a candidate and the
+        // next invocation of the asking actor is the only one there is.
+        //
+        // `windowRecords` is the verified read `lookupWindow` already performed on
+        // this invocation, so the sweep costs one append when there is something to
+        // take back and nothing at all when there is not. `withdraw` re-reads and
+        // compare-and-appends against its own head (SPEC.md §11.1 invariant 5), so
+        // a question decided between that read and this call refuses
+        // `already-decided` and is passed over rather than overwritten.
+        //
+        // `keepHash` is this invocation's own bytes, exactly as the intake sweep
+        // passes it: a sibling hook process waiting on a question about the same
+        // payload is never taken back from under it.
+        if (windowRecords !== null) {
+            const swept = withdrawAbandoned(run, streams, windowRecords, new Date().toISOString(), payloadHash(payload));
+            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\n`);
+            }
+        }
         // 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
@@ -2792,9 +5489,13 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         // 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 {
+                permission: "deny",
+                code: `hook-gate-refused:${charged.code}`,
+                detail: charged.message,
+            };
         }
-        return allow(streams, `autonomous: ${classes.join(", ")}${note}`, adapter.kind, codexCommand);
+        return { permission: "allow", reason: `autonomous: ${classes.join(", ")}${note}` };
     }
     // 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
@@ -2802,11 +5503,14 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // 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);
+    return gateHarnessCall(streams, run, classes, payload, headline, task, note, floor);
 }
-function commandHarnessHook(argv, streams, cwd, readStdin, adapter) {
+function commandHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
+    if (adapter.kind === "hermes") {
+        return hermesFailClosed(argv, streams, cwd, readStdin, adapter, waitSeam);
+    }
     try {
-        return runHarnessHook(argv, streams, cwd, readStdin, adapter);
+        return runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam);
     }
     catch (cause) {
         // A hook that throws is a hook the harness treats as a non-blocking error,
@@ -2816,6 +5520,129 @@ function commandHarnessHook(argv, streams, cwd, readStdin, adapter) {
         return deny(streams, "hook-io", `the hook failed: ${cause instanceof Error ? cause.message : String(cause)}`, adapter.kind);
     }
 }
+/**
+ * The Hermes hook's last line of defence (APRV-445): whatever happened inside,
+ * a `pre_tool_call` answer leaves this function as a verdict Hermes blocks on or
+ * as an explicit allow, and never as anything Hermes would read as an allow by
+ * default.
+ *
+ * Hermes (v2026.9.24, `agent/shell_hooks.py`) blocks on exit 2 whatever stdout
+ * says, and blocks on any other non-zero exit only when stdout carries a block
+ * directive; ANY OTHER NON-ZERO EXIT WITH AN EMPTY STDOUT IS AN ALLOW, with a
+ * warning in a log nobody reads. So this enforces two rules on every path:
+ *
+ * - a non-zero exit always carries the `{action:"block"}` directive on stdout
+ *   and is always exactly 2;
+ * - exit 0 on a pre-event is only ever the adapter's own `{}` allow. A path that
+ *   returned 0 having printed nothing is a path nobody wrote a verdict for, and
+ *   it blocks.
+ *
+ * A post-event is untouched: it never blocks (see the post path), and it prints
+ * nothing on stdout by design. A throw becomes the same block the other
+ * adapters' catch produces.
+ */
+function hermesFailClosed(argv, streams, cwd, readStdin, adapter, 
+/** APRV-427: serve's wait seam, passed through untouched (null on the CLI). */
+waitSeam) {
+    let stdout = "";
+    const tracked = {
+        out: (text) => {
+            stdout += text;
+            streams.out(text);
+        },
+        err: (text) => streams.err(text),
+    };
+    // The post-event question is answered from the raw input, once, before the
+    // run: the run itself may be what fails to read it.
+    let raw = null;
+    const reading = () => {
+        raw ??= readStdin();
+        return raw;
+    };
+    // A signal before the wait installs its own handler. The default disposition
+    // of SIGTERM and SIGINT is to die with nothing on stdout, which Hermes reads
+    // as an allow, and the wait's handler (which withdraws and prints
+    // `hook-interrupted`) exists only from the moment the hook starts waiting.
+    // This guard covers the whole run before and after that stretch; the wait's
+    // handler is prepended, so inside the wait it answers first and exits. CLI
+    // only: under `approval serve` (a wait seam) the process's signals belong to
+    // the server.
+    const onEarlySignal = (signal) => {
+        if (raw !== null && isHermesPostEvent(raw))
+            process.exit(EXIT_OK);
+        if (stdout.length === 0) {
+            try {
+                writeSync(1, harnessBlockDirective("hook-interrupted", `the hook received ${signal} before it reached a verdict; nothing authorizes this call`, "hermes").stdout);
+            }
+            catch {
+                // stdout is gone; the exit code below is the whole verdict.
+            }
+        }
+        process.exit(HERMES_DENY_EXIT);
+    };
+    const onEarlyTerm = () => onEarlySignal("SIGTERM");
+    const onEarlyInt = () => onEarlySignal("SIGINT");
+    if (waitSeam === null) {
+        process.on("SIGTERM", onEarlyTerm);
+        process.on("SIGINT", onEarlyInt);
+    }
+    try {
+        return hermesVerdict();
+    }
+    finally {
+        if (waitSeam === null) {
+            process.off("SIGTERM", onEarlyTerm);
+            process.off("SIGINT", onEarlyInt);
+        }
+    }
+    function hermesVerdict() {
+        let code;
+        try {
+            code = runHarnessHook(argv, tracked, cwd, reading, adapter, waitSeam);
+        }
+        catch (cause) {
+            // A post-event never blocks: the call already ran (see the post path).
+            if (raw !== null && isHermesPostEvent(raw))
+                return EXIT_OK;
+            if (stdout.length > 0) {
+                // A verdict was already printed; one more object would be unparseable.
+                return HERMES_DENY_EXIT;
+            }
+            return deny(tracked, "hook-io", `the hook failed: ${cause instanceof Error ? cause.message : String(cause)}`, adapter.kind);
+        }
+        const post = raw !== null && isHermesPostEvent(raw);
+        if (post)
+            return code;
+        const blocked = /"action"\s*:\s*"block"/u.test(stdout);
+        if (code === EXIT_OK && stdout.length > 0)
+            return code;
+        if (code === EXIT_OK || !blocked) {
+            if (stdout.length > 0) {
+                // Something that is not a block is already on stdout, and a second
+                // object after it is unparseable stdout, which `fail_closed` blocks and a
+                // build without it allows. The exit code is the verdict that cannot be
+                // misread, so it carries the block.
+                return HERMES_DENY_EXIT;
+            }
+            return deny(tracked, "hook-io", code === EXIT_OK
+                ? "the hook reached no verdict for this call; nothing authorizes it"
+                : `the hook exited ${String(code)} without a verdict; nothing authorizes this call`, adapter.kind);
+        }
+        return HERMES_DENY_EXIT;
+    }
+}
+/** Is this raw Hermes event a `post_tool_call`? Unreadable input is not. */
+function isHermesPostEvent(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return false;
+        return parsed["hook_event_name"] === HERMES_POST_TOOL_EVENT;
+    }
+    catch {
+        return false;
+    }
+}
 // ===========================================================================
 // Dispatch
 // ===========================================================================
@@ -2823,7 +5650,13 @@ function commandHarnessHook(argv, streams, cwd, readStdin, adapter) {
 function defaultStdin() {
     return readFileSync(0, "utf8");
 }
-export function commandHook(argv, streams, cwd, readStdin = defaultStdin) {
+export function commandHook(argv, streams, cwd, readStdin = defaultStdin, 
+/**
+ * APRV-427: where a harness hook's wait begins and ends, for `approval serve`,
+ * which runs the call off its main thread and releases its store lock while
+ * the call polls. Every CLI route omits it. See {@link HookWaitSeam}.
+ */
+waitSeam = null) {
     const sub = argv[0];
     const rest = argv.slice(1);
     if (sub === undefined) {
@@ -2833,17 +5666,14 @@ export function commandHook(argv, streams, cwd, readStdin = defaultStdin) {
         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 "codex":
-            return commandHarnessHook(rest, streams, cwd, readStdin, CODEX_ADAPTER);
-        case "classify":
-            return commandClassify(rest, streams, cwd);
-        default:
-            return usageError(streams, `unknown subcommand ${JSON.stringify(sub)} for \`approval hook\``);
+    // APRV-358: one list. `isHarnessKind` is the same predicate the write
+    // boundary and doctor use, so a kind that can be recorded is a kind that can
+    // be invoked, and neither can be added without the other.
+    if (isHarnessKind(sub)) {
+        return commandHarnessHook(rest, streams, cwd, readStdin, HARNESS_ADAPTERS[sub], waitSeam);
     }
+    if (sub === "classify")
+        return commandClassify(rest, streams, cwd);
+    return usageError(streams, `unknown subcommand ${JSON.stringify(sub)} for \`approval hook\``);
 }
 //# sourceMappingURL=hook.js.map