approval-md 0.1.0 → 0.3.0

package/dist/src/cli/hook.js

@@ -78,24 +78,27 @@ 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 { classifyCommand, commandSegmentWords, CODE_EXECUTING_RULES, CONTRIBUTOR_SUFFIX, GATE_SELF_CLASS, protectedPathClass, } from "../core/command-class.js";
 import { consumeHarnessGrant, findHarnessCarry, finishHarnessExecution, register, request, startHarnessExecution, withdraw, } from "../core/gate.js";
 import { openGateWindow, recordGateBypass, } from "../core/gate-window.js";
-import { harnessProvenance, } from "../core/harness-version.js";
+import { harnessProvenance, isHarnessKind, } from "../core/harness-version.js";
 import { abandonedAfterMs, HOOK_DEFAULT_WAIT, HOOK_RETRY_GRACE_MS, } from "../core/harness-wait.js";
 import { harnessLoopFloor, isLoopEscalated, isSideEffectingClass, loopClearance, UNKNOWN_SESSION, } from "../core/loop.js";
 import { drawSocketPathFor, drawSocketUsable } from "../core/live-draw.js";
 import { payloadHash } from "../core/payload.js";
+import { 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 { 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, 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_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, 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;
 /**
@@ -149,6 +152,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. */
@@ -217,6 +243,46 @@ 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",
     /** Malformed hook input, or a log/filesystem fact that stopped the check. */
     "hook-io",
 ];
@@ -265,7 +331,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");
@@ -276,12 +342,30 @@ 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;
+}
 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",
@@ -289,15 +373,156 @@ 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",
+    originApp: "codex-hook",
+    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,
+};
+/**
+ * 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,
 };
 /**
  * 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) {
+function decision(permission, reason, harness, codexCommand) {
     if (harness === "cursor") {
         return `${JSON.stringify({
             permission,
@@ -305,26 +530,109 @@ function decision(permission, reason, harness) {
             agent_message: reason,
         })}\n`;
     }
-    return `${JSON.stringify({
-        hookSpecificOutput: {
-            hookEventName: "PreToolUse",
-            permissionDecision: permission,
-            permissionDecisionReason: reason,
-        },
-    })}\n`;
+    if (harness === "grok") {
+        return `${JSON.stringify({ decision: permission, reason })}\n`;
+    }
+    const hookSpecificOutput = {
+        hookEventName: "PreToolUse",
+        permissionDecision: permission,
+        permissionDecisionReason: reason,
+    };
+    if (harness === "codex" && permission === "allow") {
+        if (codexCommand !== undefined)
+            hookSpecificOutput["updatedInput"] = { command: codexCommand };
+    }
+    return `${JSON.stringify({ hookSpecificOutput })}\n`;
 }
-function allow(streams, reason, harness) {
-    streams.out(decision("allow", reason, harness));
+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);
+    }
+    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;
 function deny(streams, code, detail, harness) {
     streams.out(decision("deny", `${code}: ${detail}`, harness));
-    return EXIT_OK;
+    return harness === "grok" ? GROK_DENY_EXIT : EXIT_OK;
+}
+/** 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.
  *
@@ -334,7 +642,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;
@@ -351,31 +659,42 @@ 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 responseValue = readDialect(fields, "tool_response", "toolResponse", camelCase);
+    const sessionId = readDialectString(fields, "session_id", "sessionId", camelCase);
     return {
         ok: true,
         input: {
             // The ONE shared bucket for an unreadable session (`core/loop.ts`'s
             // `UNKNOWN_SESSION`): absence accrues faster than a readable id and never
             // slower, which is the fail-closed direction.
-            sessionId: readString(fields, "session_id") ?? UNKNOWN_SESSION,
+            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,
+            toolResponseRaw: responseValue,
         },
     };
 }
@@ -823,22 +1142,166 @@ 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;
+}
 /**
- * The classifier, its scratch context, and both impure refinements, in the one
+ * 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 };
+}
+/**
+ * The classifier, its context, and all three impure refinements, in the one
  * order every caller must use.
  *
  * `hook classify` printing a different class from the one `hook claude-code`
  * decides would make the explainer a different program (APRV-108's note), and
- * that stays true now there are two refinements in the chain.
+ * that stays true now there are three refinements in the chain.
+ *
+ * `readRoots` is the one argument whose ABSENCE is the loose answer rather than
+ * the strict one (APRV-347), so it is passed explicitly at every call site: an
+ * empty list means "do not scope reads", which is what every caller outside a
+ * resolved gate scope wants and what this classifier did before the field
+ * existed.
  */
-export 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);
     return {
-        result: scratched.result,
-        notes: [...rewritten.notes, ...scratched.notes],
+        result: scoped.result,
+        notes: [...rewritten.notes, ...scratched.notes, ...scoped.notes],
     };
 }
 // ===========================================================================
@@ -894,7 +1357,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 });
@@ -903,10 +1366,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) {
@@ -1034,16 +1500,141 @@ 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.
  *
- * Only one thing about a file edit is a gate question at v0.1: whether the file
- * is one only a human may write. Everything else the harness edits is
- * `files.write.workspace`, which this repository's policy makes autonomous, and
- * routing every keystroke of ordinary editing through a gate check would spend
- * latency to reach a foregone conclusion.
+ * Every file edit is a gate question. Protected targets take their derived
+ * protected class; every other target is `files.write.workspace`. The policy
+ * decides the autonomy of either class, so changing the ordinary-file rule to
+ * manual, supervised or human-only changes the hook verdict too (APRV-304).
  *
- * ## The ordinary edit still gets a class (APRV-303)
+ * ## The ordinary edit gets a class and follows it (APRV-303, APRV-304)
  *
  * It used to get none: an unprotected target returned `null` here, and
  * `describeToolCall` answered `allow` from a branch that sits ABOVE the loop
@@ -1053,12 +1644,10 @@ const WORKSPACE_WRITE_CLASS = "files.write.workspace";
  * eight edits to the same file, under a standing floor, none of them routed and
  * none of them counted.
  *
- * The foregone conclusion is still foregone, and is still answered without
- * asking anybody: `describeToolCall` marks the call {@link FileGate.protectedPath}
- * `false`, and `runHarnessHook` allows it outright the moment it establishes
- * that no floor is standing. What it can no longer do is skip that
- * establishment. The floor predicate is now one predicate over one class for
- * every tool kind, which is what amended SPEC.md §10.2 asks for.
+ * APRV-303 made the floor predicate one predicate over one class for every tool
+ * kind. APRV-304 carries the same class through the rest of the shared path:
+ * policy resolution, human-only refusal, budgets, registration and execution
+ * accounting. An open window records the bypass before allowing the edit.
  *
  * ## The payload is the change (APRV-124)
  *
@@ -1133,6 +1722,68 @@ 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)`,
+    };
+}
+/** 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) {
@@ -1551,44 +2202,19 @@ 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.
+ * The hook's own rendering of a verdict: one decision object on stdout, in the
+ * dialect of the harness that asked.
  *
- * ## Why the wait no longer ends in a withdrawal (APRV-106, revised)
- *
- * APRV-106 retracted the request when the wait elapsed, because a retried tool
- * call was a new request with a new key and a late tap therefore authorized
- * nothing: the human spent attention on a question whose asker had left. The
- * carryover above removes the premise. A late tap now authorizes the retry, so
- * the request stays open for the policy's TTL and the timeout says so.
- *
- * What still withdraws is every path where nothing can adopt the question: a
- * SIGTERM or SIGINT (the session is going away), a thrown failure, and an intake
- * refusal partway through a multi-class command (the command cannot proceed on
- * any retry, so the classes already opened are noise in a human's queue). The
- * signal handlers are installed for the duration of the wait ONLY, and removed
- * in `finally`: a hook process is short-lived and borrowing the harness's
- * signal disposition for longer than the loop would be a side effect nobody
- * asked for.
+ * 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
@@ -1639,18 +2265,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);
+    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
@@ -2077,7 +2707,71 @@ 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.
  */
-function readReportedOutcome(input) {
+/**
+ * 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" };
+}
+function readReportedOutcome(input, adapter) {
+    if (adapter.kind === "codex")
+        return readCodexReportedOutcome(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 {
@@ -2114,7 +2808,12 @@ function readReportedOutcome(input) {
  * 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)) {
         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) {
@@ -2124,28 +2823,80 @@ 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");
     }
-    const reading = readReportedOutcome(input);
+    // 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))) {
         return report(streams, "post-tool-log-unreachable", `no log at ${logPath}; the hook writes to an existing log and never creates one. Run \`approval init\` in ${root}`);
     }
     const finished = finishHarnessExecution(logPath, {
-        sessionId: input.sessionId,
-        toolUseId: input.toolUseId,
+        sessionId: adapter.kind === "codex" ? codexBinding(input, cwd).finishSessionId : input.sessionId,
+        toolUseId: adapter.kind === "codex" ? codexBinding(input, cwd).finishToolUseId : input.toolUseId,
         outcome: reading.outcome,
         // The one member of the closed set at v0.1. It names the untrusted
         // reporter and reduces nothing.
         reportedBy: "post-tool-use",
     }, actor);
     if (!finished.ok) {
-        return report(streams, `post-tool-gate-refused:${finished.code}`, finished.message);
+        return report(streams, `post-tool-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" };
+        }
+        const parsed = parseApplyPatch(raw);
+        if (!parsed.ok)
+            return { kind: "deny", code: "hook-io", detail: parsed.detail };
+        const classified = classifyApplyPatch(parsed, cwd, protectedPaths);
+        if (!classified.ok)
+            return { kind: "deny", code: "hook-io", detail: classified.detail };
+        return {
+            kind: "gated",
+            classes: classified.classes,
+            payload: codexBinding(input, cwd).payload,
+            headline: `apply_patch ${classified.operations.length} operation(s)`,
+            notes: classified.targets.map((target) => `${target.role} ${target.path} (${target.classes.join(", ")})`),
+        };
+    }
     if (input.toolName === adapter.shellTool) {
         const raw = readString(input.toolInput, "command");
         if (raw === null) {
@@ -2155,15 +2906,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 = { command: raw, cwd: input.cwd };
+        const payload = adapter.bindToolName
+            ? codexBinding(input, cwd).payload
+            : { 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 {
@@ -2172,29 +2963,111 @@ function describeToolCall(input, adapter, protectedPaths, cwd) {
                 detail: `${classified.detail} (segment: ${classified.segment}). Rewrite it as a command the classifier can read, or run the effect through \`approval run\` with a granted token.`,
             };
         }
+        const classes = classified.classes.filter((cls) => cls !== GATE_SELF_CLASS);
+        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
+            // when the hook itself runs inside an organ directory by resolving every
+            // later side-effecting segment's words from the effective directory.
+            const possibleCwds = new Set([cwd]);
+            for (const segment of classified.segments) {
+                const parsedWords = commandSegmentWords(segment.text)?.[0];
+                if (parsedWords?.bin === "cd" && parsedWords.args.length !== 1) {
+                    return {
+                        kind: "deny",
+                        code: "hook-io",
+                        detail: "Codex Bash cwd changes must use exact `cd <directory>` with no additional words",
+                    };
+                }
+                if (parsedWords?.bin === "cd" &&
+                    (parsedWords.args[0] === "-" ||
+                        (!isAbsolute(parsedWords.args[0] ?? "") &&
+                            parsedWords.args[0] !== "." &&
+                            parsedWords.args[0] !== ".." &&
+                            !(parsedWords.args[0] ?? "").startsWith("./") &&
+                            !(parsedWords.args[0] ?? "").startsWith("../")))) {
+                    return {
+                        kind: "deny",
+                        code: "hook-io",
+                        detail: "Codex Bash cwd changes must name an absolute path, `.`, `..`, `./...`, or `../...`; OLDPWD and CDPATH-dependent operands are unsupported",
+                    };
+                }
+                if (isSideEffectingClass(segment.class)) {
+                    for (const possibleCwd of possibleCwds) {
+                        const cwdSegments = possibleCwd.split(/[/\\]+/u);
+                        const cwdClass = cwdSegments.includes(".codex")
+                            ? "policy.core"
+                            : protectedPathClass(possibleCwd, protectedPaths);
+                        if (cwdClass !== null && !classes.includes(cwdClass))
+                            classes.push(cwdClass);
+                        for (const word of parsedWords === undefined ? [] : [parsedWords.bin, ...parsedWords.args]) {
+                            const cls = protectedPathClass(resolvePathSegments(possibleCwd, word), protectedPaths);
+                            if (cls !== null && !classes.includes(cls))
+                                classes.push(cls);
+                        }
+                    }
+                }
+                if (parsedWords?.bin === "cd" && parsedWords.args.length === 1) {
+                    // Lists and conditionals may skip a cd. Retain every prior directory
+                    // and add each directory the cd could establish; later writes are
+                    // checked against their union.
+                    const priorCwds = Array.from(possibleCwds);
+                    for (const possibleCwd of priorCwds) {
+                        const lexical = resolvePathSegments(possibleCwd, parsedWords.args[0] ?? "");
+                        possibleCwds.add(lexical);
+                        try {
+                            possibleCwds.add(realpathSync(lexical));
+                        }
+                        catch {
+                            return {
+                                kind: "deny",
+                                code: "hook-io",
+                                detail: `Codex Bash cd target ${JSON.stringify(parsedWords.args[0])} could not be resolved`,
+                            };
+                        }
+                        if (possibleCwds.size > 64) {
+                            return {
+                                kind: "deny",
+                                code: "hook-io",
+                                detail: "Codex Bash command has more than 64 possible working directories",
+                            };
+                        }
+                    }
+                }
+            }
+        }
         return {
             kind: "gated",
-            classes: classified.classes.filter((cls) => cls !== GATE_SELF_CLASS),
+            classes,
             payload,
             headline: raw,
             notes: refined.notes,
             segments: classified.segments,
         };
     }
-    const gated = fileToolGate(input.toolName, input.toolInput, protectedPaths, cwd);
-    if (gated === null) {
-        return { kind: "allow", reason: `${input.toolName} names no file, so there is nothing to gate` };
-    }
-    if (!gated.protectedPath) {
+    // 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)) {
+        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: [gated.cls],
-            payload: gated.payload,
-            headline: gated.summary,
-            notes: [],
-            passthrough: `${input.toolName} is not a gated edit`,
+            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` };
+    }
     return {
         kind: "gated",
         classes: [gated.cls],
@@ -2202,7 +3075,7 @@ function describeToolCall(input, adapter, protectedPaths, cwd) {
         headline: gated.summary,
         // The tier rides in the verdict's note as well as in the payload, so an
         // `allow` says which checkout it authorized (APRV-124).
-        notes: [fileTierNote(gated)],
+        notes: gated.protectedPath ? [fileTierNote(gated)] : [],
     };
 }
 /** The environment variable that turns the sandbox requirement on (APRV-193). */
@@ -2328,6 +3201,7 @@ function runBypass(streams, input, adapter, cwd, logPath, flags, actor, window,
  * shape.
  */
 decidedOn) {
+    const codexCommand = adapter.kind === "codex" ? codexBinding(input, cwd).payload.command : undefined;
     const scope = hookScope(flags, cwd);
     const load = loadPolicy(scope.options.policy?.file === undefined
         ? { dir: scope.options.policy?.dir ?? cwd }
@@ -2336,20 +3210,16 @@ 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);
     }
-    if (described.kind === "allow")
-        return allow(streams, described.reason, adapter.kind);
-    if (described.passthrough !== undefined) {
-        // APRV-303. An ordinary workspace edit is allowed by the policy on its own
-        // merits, so there is nothing here for the window to suspend and nothing
-        // for a `gate.bypassed` record to say. The only thing that would have made
-        // this call a question is a §10.2 floor, and a window bypasses the floor
-        // outright. Answered here rather than below so the bypass log stays a
-        // record of calls the window actually let through.
-        return allow(streams, described.passthrough, adapter.kind);
+    if (described.kind === "allow") {
+        return allow(streams, described.reason, adapter.kind, codexCommand);
     }
     const classes = described.classes;
     if (classes.length === 0) {
@@ -2357,13 +3227,22 @@ decidedOn) {
         // record for the reason it is allowed outside a window: gating the gate
         // with the gate recurses, and a window that recorded its own closing verb
         // would be recording the act that ends it.
-        return allow(streams, "the approval CLI is the gate itself and is not gated by it", adapter.kind);
+        return allow(streams, "the approval CLI is the gate itself and is not gated by it", adapter.kind, codexCommand);
     }
     const mutation = classes.find((cls) => cls === "log.mutate");
     if (mutation !== undefined) {
         return deny(streams, "hook-class-human-only", `${mutation} is never reachable through the open window: the window suspends the POLICY, and the log is what the window itself is derived from. A bypass able to write the log could rewrite its own authorization. Nothing was appended; a human writes the log directory by hand or not at all.`, adapter.kind);
     }
     if (load.ok) {
+        // 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);
@@ -2400,9 +3279,10 @@ decidedOn) {
     }
     streams.err(bypassBanner(window, classes, recorded.record.seq));
     const notes = [...described.notes, ...(policyNote === null ? [] : [policyNote])];
-    return allow(streams, `gate-open: ${classes.join(", ")} bypassed by the window opened at seq ${String(window.seq)} by ${window.openedBy} (expires ${window.expiresAt}); recorded as gate.bypassed seq ${String(recorded.record.seq)}${notes.length === 0 ? "" : ` (${notes.join("; ")})`}`, adapter.kind);
+    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);
     const parsed = parseFlags(argv, {
         ...COMMON_FLAGS,
         ...POLICY_FLAGS,
@@ -2413,29 +3293,40 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         "--retry-grace": "string",
     });
     if (!parsed.ok)
-        return usageError(streams, parsed.message);
+        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.
+        const harnessHelp = adapter.kind === "grok"
+            ? HOOK_GROK_HELP
+            : adapter.kind === "muse"
+                ? HOOK_MUSE_HELP
+                : HOOK_HELP;
+        streams.out(`${harnessHelp}\n`);
         return EXIT_OK;
     }
     const extra = parsed.positionals[0];
     if (extra !== undefined) {
-        return usageError(streams, `unexpected argument ${JSON.stringify(extra)}`);
+        return configurationError(`unexpected argument ${JSON.stringify(extra)}`);
     }
     const asFlag = stringFlag(parsed.flags, "--as");
     const actor = asFlag ?? adapter.defaultActor;
     if (!PRINCIPAL_ACTOR.test(actor)) {
-        return usageError(streams, `--as expects agent:<id> or human:<id>, got ${JSON.stringify(asFlag)}`);
+        return configurationError(`--as expects agent:<id> or human:<id>, got ${JSON.stringify(asFlag)}`);
     }
     const timeoutText = stringFlag(parsed.flags, "--timeout") ?? DEFAULT_TIMEOUT;
     const timeoutMs = parseDuration(timeoutText);
     if (timeoutMs === null) {
-        return usageError(streams, `--timeout expects a duration like 30s, 9m, got ${JSON.stringify(timeoutText)}`);
+        return configurationError(`--timeout expects a duration like 30s, 9m, got ${JSON.stringify(timeoutText)}`);
     }
     const intervalText = stringFlag(parsed.flags, "--interval");
     const intervalMs = intervalText === null ? DEFAULT_INTERVAL_MS : parseDuration(intervalText);
     if (intervalMs === null) {
-        return usageError(streams, `--interval expects a duration like 500ms, 2s, got ${JSON.stringify(intervalText)}`);
+        return configurationError(`--interval expects a duration like 500ms, 2s, got ${JSON.stringify(intervalText)}`);
     }
     // APRV-287. How long the question outlives the wait, for the retry that
     // adopts it. The duration grammar has no zero, so the shortest window is
@@ -2443,12 +3334,67 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     const graceText = stringFlag(parsed.flags, "--retry-grace");
     const graceMs = graceText === null ? HOOK_RETRY_GRACE_MS : parseDuration(graceText);
     if (graceMs === null) {
-        return usageError(streams, `--retry-grace expects a duration like 5m, 30s, 1ms, got ${JSON.stringify(graceText)}`);
+        return configurationError(`--retry-grace expects a duration like 5m, 30s, 1ms, got ${JSON.stringify(graceText)}`);
     }
-    const parsedInput = parseHookInput(readStdin());
+    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) {
+            // 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 = input.hookEventName !== null && POST_TOOL_EVENTS.includes(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 = input.hookEventName !== null && POST_TOOL_EVENTS.includes(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
@@ -2459,22 +3405,64 @@ 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.
-    if (input.hookEventName !== null && POST_TOOL_EVENTS.includes(input.hookEventName)) {
+    const postToolEvent = adapter.kind === "codex"
+        ? input.hookEventName === CODEX_POST_TOOL_EVENT
+        : input.hookEventName !== null && POST_TOOL_EVENTS.includes(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
         // here: it would print a verdict object about a tool call the harness has
         // already finished, and the reason the counterpart did not land would be
         // dressed as a permission decision. A throw on this path is `post-tool-io`,
         // on stderr, at the exit code that makes the line visible.
+        //
+        // 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.
+        const settle = (code) => (adapter.kind === "grok" ? 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
+    // absent from tool_input while both the event cwd and this hook process stay
+    // at the session root (APRV-310 native v6). A decision over the visible
+    // `{command, cwd}` would therefore bind different bytes from the action the
+    // 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-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);
+    }
     if (input.toolName !== adapter.shellTool && !adapter.fileTools.includes(input.toolName)) {
-        return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind);
+        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 (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:
@@ -2511,6 +3499,40 @@ 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,
+        codexCommand,
+        windowRecords: looked.records,
+    }));
+}
+/**
+ * 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;
     // 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
@@ -2523,24 +3545,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 { permission: "allow", reason: described.reason };
     }
-    if (described.kind === "allow")
-        return allow(streams, described.reason, adapter.kind);
     const { classes, payload, headline } = described;
     /** What the history-rewrite refinement did, for the decision reason. */
     const notes = [...described.notes];
     if (classes.length === 0) {
-        return allow(streams, "the approval CLI is the gate itself and is not gated by it", adapter.kind);
+        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
@@ -2549,11 +3583,17 @@ 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.
-    const task = `hook:${input.sessionId}:${input.toolUseId ?? randomBytes(8).toString("hex")}`;
+    const task = adapter.kind === "codex"
+        ? codexBinding(input, cwd).task
+        : `hook:${input.sessionId}:${input.toolUseId ?? randomBytes(8).toString("hex")}`;
     const run = {
         logPath,
         options,
@@ -2564,6 +3604,7 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         ttlMs: load.durations.approvalTtlMs,
         harness: adapter.kind,
         originApp: adapter.originApp,
+        ...(codexCommand === undefined ? {} : { codexCommand }),
         eventVersion: input.harnessVersion,
         // Off the policy this function already loaded and validated, so the names
         // printed are the names a channel process would serve (APRV-281). Sorted
@@ -2572,7 +3613,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
@@ -2588,7 +3648,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
@@ -2596,7 +3660,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
@@ -2611,9 +3675,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).
      *
@@ -2659,26 +3723,13 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
      * refinement's own words, and the loop floor's when one applied.
      */
     const note = notes.length === 0 ? "" : ` (${notes.join("; ")})`;
-    // APRV-303, and the last thing that can answer without touching the log: an
-    // ordinary workspace edit, which the policy allows on its own merits and which
-    // is a question only while a floor stands.
-    //
-    // The order is the whole fix. Until APRV-303 this allow was printed from
-    // `describeToolCall`'s own branch, several hundred lines above the floor
-    // lookup, so a session whose Bash calls were all being routed to a human went
-    // on editing files unrouted and uncounted. Now the same allow is printed, in
-    // the same words, from BELOW the floor: the fast path is as fast as it was,
-    // and the floored path routes an Edit exactly as it routes an `echo >`,
-    // because both are `files.write.workspace` and one predicate decides.
-    if (described.passthrough !== undefined && floor === null) {
-        return allow(streams, `${described.passthrough}${note}`, adapter.kind);
-    }
     /** No class here needs a human, so nothing downstream will ask for one. */
     const unattended = floor === null && autonomies.every((autonomy) => autonomy !== "manual");
     if (unattended) {
-        const refused = unattendedGuard(logPath, load.source.path, task, looked.records);
-        if (refused !== null)
-            return deny(streams, refused.code, refused.detail, adapter.kind);
+        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")) {
         // No approval lifecycle: an autonomous action has none (amended SPEC.md
@@ -2688,9 +3739,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);
+        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
@@ -2698,7 +3753,7 @@ 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) {
     try {
@@ -2729,15 +3784,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 "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]);
     }
+    if (sub === "classify")
+        return commandClassify(rest, streams, cwd);
+    return usageError(streams, `unknown subcommand ${JSON.stringify(sub)} for \`approval hook\``);
 }
 //# sourceMappingURL=hook.js.map