approval-md 0.4.1 → 0.4.3

package/dist/src/cli/hook.js

@@ -72,13 +72,13 @@
  * auditor holding the log alone. See `docs/claude-code-hook.md`.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, realpathSync, statSync, writeSync } from "node:fs";
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync, writeSync, } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve as resolvePathSegments, sep, } from "node:path";
-import { attestationRefusal, checkAttestation } from "../core/attest.js";
+import { attestationRefusal, checkAttestation, checkAttestationOfBytes } from "../core/attest.js";
 import { childEnvironment } from "../core/child-env.js";
-import { classifyCommand, commandSegmentShapes, commandSegmentWords, CODE_EXECUTING_RULES, CONTRIBUTOR_SUFFIX, GATE_SELF_CLASS, isCredentialPath, protectedPathClass, } from "../core/command-class.js";
+import { classifyCommand, commandSegmentShapes, commandSegmentWords, CODE_EXECUTING_RULES, CONTRIBUTOR_SUFFIX, GATE_SELF_CLASS, isCredentialPath, NODE_SKILL_SCRIPT_RULE, protectedPathClass, SKILL_SCRIPT_RULE, } from "../core/command-class.js";
 import { consumeHarnessGrant, findHarnessCarry, finishHarnessExecution, isProposalTask, register, request, startHarnessExecution, withdraw, } from "../core/gate.js";
 import { openGateWindow, recordGateBypass, } from "../core/gate-window.js";
 import { harnessProvenance, isHarnessKind, } from "../core/harness-version.js";
@@ -89,7 +89,8 @@ import { appendLockHeld, DEFAULT_LOCK_RETRY_MS, DEFAULT_LOCK_TIMEOUT_MS, } from
 import { settleTerminationGuards } from "../core/log-lock.js";
 import { payloadHash } from "../core/payload.js";
 import { classifyApplyPatch, parseApplyPatch } from "../core/apply-patch.js";
-import { loadPolicy, parseDuration } from "../core/policy-load.js";
+import { loadPolicy, loadPolicyText, parseDuration, POLICY_FILENAMES, } from "../core/policy-load.js";
+import { isRecordableToolName, toolMapVerdict, UNMAPPED_TOOL_CLASS, } from "../core/tool-map.js";
 import { READ_OUT_OF_SCOPE_CLASS, effectiveReadRoots, isInReadScope, readTargetsOf, renderReadRoots, } from "../core/read-scope.js";
 import { harnessLaunchNeedsRule, harnessLaunchUnruledRefusal, humanOnlyRefusal, resolve as resolvePolicy, } from "../core/policy-match.js";
 import { payloadOf, readVerifiedRecords, requestExpiresAt, requestState, useVerifiedSnapshots, } from "../core/state.js";
@@ -812,6 +813,100 @@ function toolRuleOf(adapter, input) {
     }
     return adapter.toolRules(input.toolName, input.toolInput);
 }
+/**
+ * Is this call one the adapter's own tables leave unclaimed? (APRV-499.)
+ *
+ * Unclaimed means: not the shell tool, not a file or read tool, not a
+ * pass-through tool, and not a tool the hard-coded rule table answers (gated OR
+ * read). Exactly these calls reach the policy's `tools` mapping and its
+ * unmapped-tool default, and before APRV-499 exactly these were answered "not a
+ * gated tool". The adapter's tables keep precedence because they read the
+ * call's arguments, and a `tools` entry reads only its name.
+ */
+function unclaimedTool(adapter, input) {
+    if (input.toolName === adapter.shellTool)
+        return false;
+    if (adapter.fileTools.includes(input.toolName))
+        return false;
+    if (adapter.readTools.includes(input.toolName))
+        return false;
+    if (adapter.passThroughTools?.includes(input.toolName) === true)
+        return false;
+    return toolRuleOf(adapter, input) === null;
+}
+/**
+ * The policy file's bytes, found the way `loadPolicy` finds them: `--policy`
+ * when given, else the first of {@link POLICY_FILENAMES} in the policy
+ * directory, else in `cwd`. `null` when there is none to read.
+ *
+ * Read ONCE and handed to both the parse and the attestation hash (APRV-142's
+ * rule, applied to this hook's unclaimed-tool answer), so no file swap between
+ * the two can attest one policy and decide by another.
+ */
+function readHookPolicyBytes(options, cwd) {
+    const candidates = options.policy?.file === undefined
+        ? POLICY_FILENAMES.map((filename) => join(options.policy?.dir ?? cwd, filename))
+        : [options.policy.file];
+    for (const candidate of candidates) {
+        try {
+            return { path: candidate, bytes: readFileSync(candidate) };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function unclaimedStanding(options, cwd, toolName, records) {
+    const read = readHookPolicyBytes(options, cwd);
+    if (read === null)
+        return { kind: "decide" };
+    const load = loadPolicyText(read.path, read.bytes.toString("utf8"));
+    if (!load.ok)
+        return { kind: "decide" };
+    if (toolMapVerdict(load.policy, toolName).kind !== "not-gated")
+        return { kind: "decide" };
+    if (records === null) {
+        return {
+            kind: "unattested",
+            code: "hook-io",
+            detail: `${toolName} is outside the gate only under an attested policy, and the log that would show the attestation could not be read and verified; nothing was appended`,
+        };
+    }
+    const refusal = attestationRefusal(checkAttestationOfBytes(records, read.bytes));
+    if (refusal === null)
+        return { kind: "ungated" };
+    return {
+        kind: "unattested",
+        code: `hook-gate-refused:${refusal.code}`,
+        detail: `${refusal.message}. ${toolName} is a tool this adapter does not classify, and whether the policy gates it (a \`tools\` entry, \`defaults.unmapped_tool\`) is a question only the attested policy answers, so the on-disk file is not read as "not a gated tool" until a human attests it. Nothing was appended.`,
+    };
+}
+/**
+ * {@link unclaimedStanding} for a caller that has not read the log: the fast
+ * path and the post-execution half. One verified read, resumed behind the
+ * daemon's snapshot (APRV-188) where there is one.
+ */
+function unclaimedUngated(flags, cwd, toolName) {
+    const { logPath, options } = hookScope(flags, cwd);
+    useVerifiedSnapshots(true);
+    const read = readVerifiedRecords(logPath);
+    return unclaimedStanding(options, cwd, toolName, read.ok ? read.records : null).kind === "ungated";
+}
+/**
+ * The `hook-policy-unavailable` detail (APRV-499, refutation S2): the load's
+ * own code and message, the first per-entry errors it computed, and the
+ * repair, so the human reading the refusal is told what to change.
+ */
+function policyUnavailableDetail(load) {
+    const errors = load.errors ?? [];
+    const shown = errors
+        .slice(0, 5)
+        .map((error) => `${error.path.length === 0 ? "(root)" : error.path}: ${error.message}`);
+    const more = errors.length > shown.length ? `; and ${String(errors.length - shown.length)} more` : "";
+    const listed = shown.length === 0 ? "" : ` (${shown.join("; ")}${more})`;
+    return `${load.code}: ${load.message}${listed}; every class resolves to manual and the hook cannot verify a decision. Repair: correct ${shown.length === 0 ? "the policy file" : "each entry named above"}, then have a human attest the result (\`approval policy attest\`); an edited policy is inoperative until then`;
+}
 /**
  * Every harness this runtime speaks a hook protocol for, by kind (APRV-358).
  *
@@ -2087,13 +2182,256 @@ export function refineWriteScope(result, roots, cwd) {
     }
     return { result: { ok: true, segments, classes }, notes };
 }
+// ===========================================================================
+// Skill scripts, the disk half (APRV-502)
+// ===========================================================================
 /**
- * The classifier, its context, and all four impure refinements, in the one
+ * The rules whose segments this pass judges: an interpreter running
+ * `skills/<skill>/scripts/<file>`, which the pure classifier answers
+ * `exec.local` from the TEXT alone.
+ */
+const SKILL_SCRIPT_RULES = [SKILL_SCRIPT_RULE, NODE_SKILL_SCRIPT_RULE];
+/** The `code` of a filesystem error, or `null`. */
+function fsErrorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return null;
+    const code = error.code;
+    return typeof code === "string" ? code : null;
+}
+/**
+ * Judge one skill script from one working directory (APRV-502).
+ *
+ * `script` is the path the classifier bound, `skills/<skill>/scripts/<file>`
+ * or an absolute `.hermes` spelling of it, so its parent is the spelled root
+ * `<base>/skills/<skill>/scripts` and nothing needs re-parsing. `<base>` is
+ * the directory the shape was spelled from: the working directory for the
+ * relative shape, the `.hermes` or `.hermes/profiles/<p>` directory for the
+ * absolute one. Both shapes put exactly three segments between base and root.
+ *
+ * ## Why an unreadable or absent script lets the text answer stand
+ *
+ * This pass can only tighten, like {@link resolvedPathClasses}, and where the
+ * disk cannot be read it has nothing to tighten WITH. That case is not
+ * hypothetical; it is the production shape. Under co-location the daemon that
+ * answers `approval hook hermes` runs as the `approvald` user and the resident's
+ * Hermes home (`/home/hermes/.hermes`) is mode 0700 owned by `hermes`, so
+ * `realpath` of the script fails with EACCES on every live box (checked
+ * read-only on one 2026-10-07). Refusing there would deny every skill script
+ * fleet-wide, which is the outage APRV-502 exists to end, so the answer is the
+ * text's and a note says the disk pass could not look. `resolvedPathClasses`
+ * has exactly the same property for the same reason. An absent file
+ * (ENOENT, ENOTDIR) is treated the same way: there is nothing on disk to run,
+ * and the interpreter will fail on its own. What the text already guarantees
+ * in both cases is the shape: no `..`, no variable, no glob, and every
+ * protected and credential tier ahead of the rule.
+ *
+ * ## Where the disk CAN be read, everything off the plain shape refuses
+ *
+ * - A real path landing on a credential or protected path refuses, naming the
+ *   landing. It does not take the landing's class: for `bun` and `python3` the
+ *   direct spelling of a protected path is refused by the classifier (the
+ *   protected scan runs only after a table row matches), so taking the class
+ *   would answer a symlinked spelling MORE loosely than the direct one under a
+ *   policy where that class is looser than a refusal (the A502 refutation's
+ *   S2: `cron.manage` autonomous in the village template).
+ * - No component of `skills/<skill>/scripts` may be a symlink: the real root
+ *   must equal `realpath(base)/skills/<skill>/scripts`. A symlinked base or
+ *   working directory is fine, because both sides are resolved.
+ * - The real path of the script must sit strictly under that real root, so a
+ *   file symlink out of `skills/<skill>/scripts/` refuses. A dangling symlink
+ *   is judged by where it points, resolved through the deepest existing
+ *   ancestor of its target, so a link whose target does not exist YET cannot
+ *   be placed now and filled later.
+ */
+function judgeSkillScript(script, cwd, protectedPaths) {
+    const spelled = resolvePathSegments(cwd, script);
+    const root = dirname(spelled);
+    let real;
+    try {
+        real = realpathSync(spelled);
+    }
+    catch (error) {
+        const code = fsErrorCode(error);
+        if (code === "EACCES" || code === "EPERM") {
+            return { kind: "unseen", why: `${spelled} cannot be read by this process (${code})` };
+        }
+        if (code === "ELOOP") {
+            return { kind: "refused", detail: `${spelled} is a symlink loop (ELOOP)` };
+        }
+        if (code !== "ENOENT" && code !== "ENOTDIR") {
+            return { kind: "refused", detail: `${spelled} could not be resolved (${code ?? "unknown error"})` };
+        }
+        // Absent, or a dangling symlink. Only the second has anything to judge.
+        let target = null;
+        try {
+            if (lstatSync(spelled).isSymbolicLink())
+                target = readlinkSync(spelled);
+        }
+        catch (inner) {
+            const innerCode = fsErrorCode(inner);
+            if (innerCode === "EACCES" || innerCode === "EPERM") {
+                return { kind: "unseen", why: `${spelled} cannot be read by this process (${innerCode})` };
+            }
+            target = null;
+        }
+        if (target === null) {
+            return { kind: "unseen", why: `${spelled} does not exist (${code})` };
+        }
+        real = canonicalPath(resolvePathSegments(dirname(spelled), target));
+    }
+    if (isCredentialPath(real)) {
+        return {
+            kind: "refused",
+            detail: `${script} resolves to ${real}, a credential path (account.credential)`,
+        };
+    }
+    const protectedClass = protectedPathClass(real, protectedPaths);
+    if (protectedClass !== null) {
+        return {
+            kind: "refused",
+            detail: `${script} resolves to ${real}, a protected path (${protectedClass})`,
+        };
+    }
+    // `<base>/skills/<skill>/scripts`: three segments up from the root is base.
+    const skill = basename(dirname(root));
+    const base = dirname(dirname(dirname(root)));
+    let realRoot;
+    let realBase;
+    try {
+        realRoot = realpathSync(root);
+        realBase = realpathSync(base);
+    }
+    catch (error) {
+        // The script resolved and a directory above it did not: two reads of one
+        // disk disagreeing. Nothing here can vouch for that.
+        return {
+            kind: "refused",
+            detail: `${root} could not be resolved (${fsErrorCode(error) ?? "unknown error"}) although the script inside it did`,
+        };
+    }
+    const expectedRoot = join(realBase, "skills", skill, "scripts");
+    if (realRoot !== expectedRoot) {
+        return {
+            kind: "refused",
+            detail: `${root} resolves to ${realRoot}, not ${expectedRoot}: a component of skills/${skill}/scripts is a symlink`,
+        };
+    }
+    if (!isBelow(real, realRoot)) {
+        return {
+            kind: "refused",
+            detail: `${script} resolves to ${real}, outside the directory it was spelled in (${realRoot})`,
+        };
+    }
+    return { kind: "inside" };
+}
+/**
+ * The directories a segment of a command line may run in: the hook's `cwd`,
+ * plus every directory an earlier literal `cd` or `pushd` could have moved to
+ * (a `cd` may or may not have run, `||` and a failing `cd` included, so both
+ * sides are kept, as {@link resolvedPathClasses} keeps them). `null` when an
+ * earlier segment moves to a directory the text cannot name: `cd $X`, `cd ~`,
+ * a bare `cd`, `cd -`, `popd`, or a `cd` carrying flags.
+ */
+function skillScriptCwds(segments, index, cwd) {
+    let cwds = [cwd];
+    for (const earlier of segments.slice(0, index)) {
+        const parsed = commandSegmentWords(earlier.text)?.[0];
+        if (parsed === undefined)
+            continue;
+        const bin = basename(parsed.bin);
+        if (bin === "popd")
+            return null;
+        if (bin !== "cd" && bin !== "pushd")
+            continue;
+        const target = parsed.args[0];
+        if (parsed.args.length !== 1 || target === undefined || target.startsWith("-"))
+            return null;
+        if (/[$`*?[{~]/u.test(target))
+            return null;
+        cwds = [...new Set([...cwds, ...cwds.map((from) => resolvePathSegments(from, target))])];
+        if (cwds.length > 64)
+            return null;
+    }
+    return cwds;
+}
+/**
+ * Check every skill-script segment against the disk (APRV-502).
+ *
+ * IMPURE by design and by contract, like the other passes: it resolves paths.
+ * It only ever TIGHTENS. A segment whose script resolves anywhere but a file
+ * under the real `skills/<skill>/scripts/` directory it was spelled in (a
+ * credential or protected landing, a path outside the real root, a symlinked
+ * component of the root) turns the whole classification into an
+ * `unclassified` failure naming the landing, which the hook denies as
+ * `hook-unclassified`; and one the disk cannot show (unreadable, absent, or
+ * after a `cd` the text cannot name) keeps the text's `exec.local` with a note
+ * saying the pass could not look. See {@link judgeSkillScript} for why that
+ * last case is deliberate, and why a protected landing refuses rather than
+ * taking the landing's class.
+ *
+ * `cwd` is the directory the command runs in: the per-call Hermes `workdir`
+ * when the harness states one (absolute only), the hook's own directory
+ * elsewhere. It is used only to tighten, so a working directory the party under
+ * oversight reported cannot loosen anything here (SPEC.md §11.1 invariant 4).
+ * Nothing here reads `HERMES_HOME`: the daemon under `approval serve` does not
+ * carry it.
+ */
+export function refineSkillScripts(result, cwd, protectedPaths) {
+    if (!result.ok)
+        return { result, notes: [] };
+    if (!result.segments.some((segment) => SKILL_SCRIPT_RULES.includes(segment.rule))) {
+        return { result, notes: [] };
+    }
+    const notes = [];
+    for (const [index, segment] of result.segments.entries()) {
+        if (!SKILL_SCRIPT_RULES.includes(segment.rule) || segment.class !== "exec.local")
+            continue;
+        const script = segment.path;
+        if (script === undefined) {
+            // The classifier binds the script on every segment of these rules, so
+            // a segment without one is two reads of the same bytes disagreeing.
+            return {
+                result: {
+                    ok: false,
+                    code: "unclassified",
+                    segment: segment.text,
+                    detail: `skill-script segment carries no script path, so it cannot be checked against the disk`,
+                },
+                notes,
+            };
+        }
+        const cwds = skillScriptCwds(result.segments, index, cwd);
+        if (cwds === null) {
+            notes.push(`skill-script-unverified: an earlier cd moves to a directory the text cannot name, so ${script} was not checked against the disk and stays exec.local`);
+            continue;
+        }
+        for (const from of cwds) {
+            const judged = judgeSkillScript(script, from, protectedPaths);
+            if (judged.kind === "refused") {
+                return {
+                    result: {
+                        ok: false,
+                        code: "unclassified",
+                        segment: segment.text,
+                        detail: `skill script escapes its directory: ${judged.detail}. A skill script must be a file under the real skills/<skill>/scripts/ directory it is spelled in, with no symlink in that directory's own path`,
+                    },
+                    notes,
+                };
+            }
+            if (judged.kind === "unseen") {
+                notes.push(`skill-script-unverified: ${judged.why}, so the disk pass could not look and ${script} stays exec.local`);
+            }
+        }
+    }
+    return { result, notes };
+}
+/**
+ * The classifier, its context, and all five 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 four refinements in the chain.
+ * that stays true now there are five 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
@@ -2116,9 +2454,18 @@ export function classifyForHook(command, protectedPaths, cwd, readRoots = []) {
     // it is the narrowest, and because nothing after it would re-read a segment
     // it has already tightened.
     const written = refineWriteScope(scoped.result, resolveWriteRoots(cwd), cwd);
+    // APRV-502. Touches only the two skill-script rules, which no pass above
+    // reads, so its place in the chain changes nothing for any other segment.
+    const scripted = refineSkillScripts(written.result, cwd, protectedPaths);
     return {
-        result: written.result,
-        notes: [...rewritten.notes, ...scratched.notes, ...scoped.notes, ...written.notes],
+        result: scripted.result,
+        notes: [
+            ...rewritten.notes,
+            ...scratched.notes,
+            ...scoped.notes,
+            ...written.notes,
+            ...scripted.notes,
+        ],
     };
 }
 // ===========================================================================
@@ -3066,6 +3413,8 @@ task) {
             append,
             presentedPayloadHash: hash,
             spendingTask: task,
+            // APRV-499 (refutation S3): a mapped or unmapped spend names its tool.
+            ...(run.harnessTool === undefined ? {} : { harnessTool: run.harnessTool }),
         }));
         if (!spent.ok)
             return { code: spent.code, message: `${key}: ${spent.message}` };
@@ -3230,8 +3579,15 @@ known = null) {
  * is recorded through {@link spendUnderLock}, which takes the shared pause.
  */
 function* recordUnattended(run, task, classes, hash) {
+    const harnessTool = run.harnessTool;
     for (const cls of classes) {
-        const started = yield* spendUnderLock(run.logPath, run.options.append, (append) => startHarnessExecution(run.logPath, { task, actionKey: `${task}:${cls}`, cls, payload_hash: hash }, run.actor, { ...run.options, append }));
+        const started = yield* spendUnderLock(run.logPath, run.options.append, (append) => startHarnessExecution(run.logPath, {
+            task,
+            actionKey: `${task}:${cls}`,
+            cls,
+            payload_hash: hash,
+            ...(harnessTool === undefined ? {} : { harness_tool: harnessTool }),
+        }, run.actor, { ...run.options, append }));
         if (!started.ok)
             return { code: started.code, message: `${cls}: ${started.message}` };
     }
@@ -3543,6 +3899,9 @@ floor = null) {
         const registered = register(run.logPath, { task, envelope }, run.actor, {
             ...run.options,
             ...(provenance === null ? {} : { harness: provenance }),
+            // APRV-499: the hook is the one caller that may declare the reserved
+            // harness.tool.unmapped class.
+            toolMapHook: true,
         });
         if (!registered.ok) {
             return sayDeny(`hook-gate-refused:${registered.code}`, registered.message);
@@ -4276,7 +4635,14 @@ function runPostToolUse(flags, streams, cwd, input, actor, adapter) {
         // nothing, and the close below finds no start and says so in its own words.
         !adapter.readTools.includes(input.toolName) &&
         // APRV-445: a tool the rule table gated wrote a start like any other.
-        toolRuleOf(adapter, input)?.kind !== "gated") {
+        toolRuleOf(adapter, input)?.kind !== "gated" &&
+        // APRV-499: an unclaimed tool the policy maps, or one it records or asks
+        // about as unmapped, wrote a start too. So did any unclaimed tool whose
+        // policy no longer loads or is not the attested one, as far as this half
+        // can tell, so that one goes on to the close, which finds the start or says
+        // there is none. Only an ATTESTED policy that loads and leaves the tool
+        // outside the gate keeps this answer (fix round 1, refutation B1).
+        (!unclaimedTool(adapter, input) || unclaimedUngated(flags, cwd, 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) {
@@ -4317,7 +4683,23 @@ function runPostToolUse(flags, streams, cwd, input, actor, adapter) {
     }
     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, readRoots = []) {
+function describeToolCall(input, adapter, protectedPaths, cwd, readRoots = [], 
+/**
+ * The loaded policy whose `tools` mapping and `defaults.unmapped_tool` an
+ * unclaimed call is answered by (APRV-499), or `null` when there is none to
+ * read (the open window over a policy that did not load).
+ */
+toolPolicy = null, 
+/**
+ * May an unclaimed call the policy leaves outside the gate be described as
+ * "not a gated tool"? (APRV-499 fix round 1, refutations B1 and S1.) The
+ * closed path passes `true` and checks the attestation on the allow it gets
+ * back. The open window passes `true` only for an attested policy that
+ * loads; otherwise an unclaimed call is described under
+ * `harness.tool.unmapped`, so the bypass RECORDS it rather than letting it
+ * run unrecorded on the word of a file nobody vouched for.
+ */
+ungatedAllowed = true) {
     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
@@ -4536,6 +4918,42 @@ function describeToolCall(input, adapter, protectedPaths, cwd, readRoots = []) {
             notes: [],
         };
     }
+    // APRV-499: a call the adapter's own tables leave unclaimed (every MCP tool
+    // among them) is answered by the policy's `tools` mapping, first match wins,
+    // then by `defaults.unmapped_tool`. Below the rule table and the shell, and
+    // above the read and file branches only because those two never see an
+    // unclaimed call: the predicate excludes them. The payload is the whole call,
+    // as the rule table's is, so a grant binds every argument; only the NAME is
+    // written to the log, on the start record.
+    if (unclaimedTool(adapter, input)) {
+        const verdict = toolPolicy === null ? { kind: "not-gated" } : toolMapVerdict(toolPolicy, input.toolName);
+        if (verdict.kind === "not-gated" && ungatedAllowed) {
+            return { kind: "allow", reason: `${input.toolName} is not a gated tool`, unclaimed: true };
+        }
+        // Refutation S4: a name the record could not carry is refused here, by
+        // name, before anything is appended, rather than at the write boundary.
+        if (!isRecordableToolName(input.toolName)) {
+            return {
+                kind: "deny",
+                code: "hook-io",
+                detail: `tool-name-invalid: ${JSON.stringify(input.toolName.slice(0, 80))}${input.toolName.length > 80 ? "…" : ""} is classified by the policy's tool mapping, and a tool so classified is recorded by name, which must be 1 to 256 of letters, digits, _, ., : and - (the characters a tools entry can match). Nothing was appended`,
+            };
+        }
+        const cls = verdict.kind === "not-gated" ? UNMAPPED_TOOL_CLASS : verdict.cls;
+        const note = verdict.kind === "mapped"
+            ? `tools entry ${String(verdict.index)} (${JSON.stringify(verdict.match)}) maps ${input.toolName} to ${verdict.cls} (APRV-499)`
+            : verdict.kind === "unmapped"
+                ? `${input.toolName} matches no tools entry; defaults.unmapped_tool: ${verdict.mode} (APRV-499)`
+                : `${input.toolName} is outside the gate only under an attested policy that loads, and this one ${toolPolicy === null ? "did not load" : "is not attested"}, so it is described as ${UNMAPPED_TOOL_CLASS} (APRV-499)`;
+        return {
+            kind: "gated",
+            classes: [cls],
+            payload: { tool: input.toolName, input: input.toolInput },
+            headline: `${input.toolName} (${cls})`,
+            notes: [note],
+            harnessTool: input.toolName,
+        };
+    }
     // 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.
@@ -5177,7 +5595,18 @@ decidedOn) {
     // 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));
+    resolveReadRoots(cwd, policyRootOf(load, scope.root), load.ok ? load.policy.read_scope?.roots : undefined), 
+    // APRV-499. The window suspends the policy's ANSWER, not its mapping: a
+    // mapped or unmapped tool is described under its class here too, so the
+    // bypass record names it.
+    load.ok ? load.policy : null, 
+    // Fix round 1 (refutations S1 and B1): "not a gated tool" is believed only
+    // from an attested policy that loads. A policy that did not load, or one
+    // nobody attested, cannot say a tool is outside the gate, so the call is
+    // described under harness.tool.unmapped and the bypass records it: a
+    // window being open does not let a call run unrecorded.
+    unclaimedStanding(scope.options, cwd, input.toolName, decidedOn?.records ?? null).kind ===
+        "ungated");
     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);
     }
@@ -5500,28 +5929,41 @@ function* runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
         input.toolName !== adapter.shellTool &&
         !adapter.fileTools.includes(input.toolName)) {
         if (!adapter.readTools.includes(input.toolName)) {
-            return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+            // APRV-499: an unclaimed tool is answered here, with one policy load,
+            // only when the policy loads and neither maps it nor declares
+            // `defaults.unmapped_tool`. Otherwise it goes on to the path below, where
+            // a mapped or unmapped call is classified and a policy that did not load
+            // is refused.
+            // Fix round 1 (refutation B1): and only when those bytes are the ATTESTED
+            // policy, which costs one verified read of the log. Anything else goes on
+            // to the path below, which refuses it in the gate's own words or, under
+            // an open window, records the bypass.
+            if (unclaimedUngated(parsed.flags, cwd, input.toolName)) {
+                return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+            }
         }
-        // APRV-347, and the placement is the whole of its cost. A read tool call is
-        // the most frequent event a session produces, and before this task it was
-        // answered here with no policy load, no verified read of the log and no
-        // window lookup. Everything below this line is expensive, so the reads that
-        // do not need it must not pay for it.
-        //
-        // The short-circuit is sound because `read_scope` is ADDITIVE: it can only
-        // widen the roots, so a target already inside the BUILT-IN roots is inside
-        // the effective ones whatever the policy says, and the policy need not be
-        // read to know it. A target outside them falls through, the policy is
-        // loaded below, and `describeToolCall` asks again with the widened set —
-        // which is where a policy-declared root actually takes effect.
-        //
-        // The cost of the fast path is a handful of `realpath` calls and no process
-        // spawn, provided the hook is configured with `--dir` as the docs show
-        // (otherwise `hookScope` runs `git rev-parse` to find the primary).
-        const early = hookScope(parsed.flags, cwd);
-        if (credentialReadGate(input.toolName, input.toolInput, cwd) === null &&
-            readToolGate(input.toolName, input.toolInput, resolveReadRoots(cwd, early.root), cwd) === null) {
-            return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+        else {
+            // APRV-347, and the placement is the whole of its cost. A read tool call is
+            // the most frequent event a session produces, and before this task it was
+            // answered here with no policy load, no verified read of the log and no
+            // window lookup. Everything below this line is expensive, so the reads that
+            // do not need it must not pay for it.
+            //
+            // The short-circuit is sound because `read_scope` is ADDITIVE: it can only
+            // widen the roots, so a target already inside the BUILT-IN roots is inside
+            // the effective ones whatever the policy says, and the policy need not be
+            // read to know it. A target outside them falls through, the policy is
+            // loaded below, and `describeToolCall` asks again with the widened set —
+            // which is where a policy-declared root actually takes effect.
+            //
+            // The cost of the fast path is a handful of `realpath` calls and no process
+            // spawn, provided the hook is configured with `--dir` as the docs show
+            // (otherwise `hookScope` runs `git rev-parse` to find the primary).
+            const early = hookScope(parsed.flags, cwd);
+            if (credentialReadGate(input.toolName, input.toolInput, cwd) === null &&
+                readToolGate(input.toolName, input.toolInput, resolveReadRoots(cwd, early.root), cwd) === null) {
+                return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+            }
         }
     }
     // APRV-188. From here on this process may resume a verified read behind the
@@ -5621,7 +6063,7 @@ function* decideHarnessSteps(decide) {
         return {
             permission: "deny",
             code: "hook-policy-unavailable",
-            detail: `${load.code}: ${load.message}; every class resolves to manual and the hook cannot verify a decision`,
+            detail: policyUnavailableDetail(load),
         };
     }
     const protectedPaths = load.policy.protected_paths ?? [];
@@ -5633,12 +6075,43 @@ function* decideHarnessSteps(decide) {
     // 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, readRoots);
+    const described = describeToolCall(input, adapter, protectedPaths, cwd, readRoots, load.policy);
     if (described.kind === "deny") {
         return { permission: "deny", code: described.code, detail: described.detail };
     }
     if (described.kind === "allow") {
-        return { permission: "allow", reason: described.reason };
+        if (described.unclaimed !== true)
+            return { permission: "allow", reason: described.reason };
+        // APRV-499 fix round 1 (refutation B1): the on-disk policy leaves this call
+        // outside the gate, and that is believed only of the ATTESTED policy. The
+        // log is required for that, exactly as it is for an unattended Bash call.
+        if (!existsSync(logPath) && !existsSync(dirname(logPath))) {
+            return {
+                permission: "deny",
+                code: "hook-log-unreachable",
+                detail: `no log at ${logPath}, so whether the policy that leaves ${input.toolName} ungated is the attested one cannot be established; 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`,
+            };
+        }
+        let records = windowRecords;
+        if (records === null) {
+            const read = readVerifiedRecords(logPath);
+            if (!read.ok)
+                return { permission: "deny", code: "hook-io", detail: read.message };
+            records = read.records;
+        }
+        const standing = unclaimedStanding(options, cwd, input.toolName, records);
+        if (standing.kind === "ungated")
+            return { permission: "allow", reason: described.reason };
+        if (standing.kind === "unattested") {
+            return { permission: "deny", code: standing.code, detail: standing.detail };
+        }
+        // The file changed between the two reads of this one decision: refuse,
+        // and the next call decides against whatever is there then.
+        return {
+            permission: "deny",
+            code: "hook-policy-unavailable",
+            detail: `the policy file changed while ${input.toolName} was being decided; nothing was appended, and a retry is decided against the file as it then stands`,
+        };
     }
     const { classes, payload, headline } = described;
     /** What the history-rewrite refinement did, for the decision reason. */
@@ -5693,6 +6166,7 @@ function* decideHarnessSteps(decide) {
         // changed when an operator reordered their policy would read as a change of
         // state.
         channels: Object.keys(load.policy.channels ?? {}).sort(),
+        ...(described.harnessTool === undefined ? {} : { harnessTool: described.harnessTool }),
     };
     const resolutions = classes.map((cls) => resolvePolicy(load, cls));
     const autonomies = resolutions.map((resolution) => resolution.autonomy);