← Files Atbash SafetyARCHIVED FILE

runtime/pre-tool-use.cjs

10.8 KB · Nov 22, 2026 · 12:12 UTC

↓ Download file

See the change to this file →

"use strict";
// The process the host starts (runtime/pre-tool-use.cjs). Plain CommonJS, no dependencies, never
// bundled, and it never loads the native SDK. It runs the real hook - the shim, which loads the
// bundle and the native addon - in a CHILD process, and keeps its own clock.
//
// Why a second process: the shim's deadline timer lives on the shim's event loop. A synchronous
// stall in that process - the native addon's load held by an antivirus scanner (measured on
// 2026-10-20: over 25 s for atbash.node under a PowerShell-started node), a hang inside the addon,
// a suspended process - keeps that timer from ever running, and the host's own timeout (35 s)
// is a permit on both hosts. The supervisor's loop is never blocked by the child, so its timer
// runs whatever the child does: past the deadline the child is killed and the call is denied.
//
// The answer the host sees is decided here, from what the child produced:
//   - exit 0, an empty stdout AND the shim's permit sign on the private fd 3 pipe: the bundle's
//     explicit permit - nothing is written. The sign is written from the shim's exit listener, so
//     a child that ends 0 without running its listeners (process.reallyExit(0), a native exit(0))
//     has no sign and is denied: silence alone is never a permit;
//   - exit 0 with exactly one PreToolUse deny: that deny, re-serialized here;
//   - anything else - another exit code, a signal, unparseable or extra output, a child that
//     could not start, a child still running at the deadline: a deny with exit 0.
// The child's stderr is relayed to the host's stderr (the transcript), bounded, so the host's
// output handles are held by this process alone: a killed child whose teardown the OS defers (a
// scanner holding it in a kernel wait) cannot keep the host waiting for end-of-file.
//
// What this cannot close: a stall of THIS process before its timer is armed (node itself not
// starting) or while it starts the child (process creation held by a scanner in this process's
// context) - only the host timeout ends those; this file loads nothing but node built-ins. Code
// preloaded into this process (NODE_OPTIONS=--require) runs here as it runs in the shim: the
// supervisor shares the shim's in-process trust boundary (src/hook/shim.cjs, header) and adds none.
const { spawn } = require("node:child_process");
const fs = require("node:fs");
const path = require("node:path");

// Taken once, before anything else in the process can run (the shim does the same).
const writeSync = fs.writeSync;

// The shim's own deadline bounds (src/hook/shim.cjs). The supervisor fires after the shim's
// deadline, so a live shim always answers first with its own reason, and still well under the
// host's 35 s: 30 s (the largest shim deadline) + 1.5 s = 31.5 s from the supervisor's start.
const DEFAULT_DEADLINE_MS = 28000;
const MIN_DEADLINE_MS = 1000;
const MAX_DEADLINE_MS = 30000;
const SUPERVISOR_MARGIN_MS = 1500;
// The largest deny written to the host, in serialized bytes - the shim's bound (see there).
const MAX_DENY_BYTES = 3584;
// The child's stdout is at most one bounded deny; anything far larger is not a decision.
const MAX_CHILD_STDOUT_BYTES = 16384;
// The child's log lines relayed to the host's stderr, in total. Written synchronously and kept,
// with the supervisor's own short reason lines, under the smallest pipe buffer a host hands a hook
// (4 KiB), so a host that never reads stderr cannot block this process's event loop - and with it
// the deadline. Lines past the bound are dropped with one note.
const MAX_STDERR_RELAY_BYTES = 2048;
// The shim's permit sign (src/hook/shim.cjs PERMIT_SIGN), on the private fd 3 pipe.
const PERMIT_SIGN = "atbash-permit\n";
const WRITE_RETRY_WAIT_MS = 25;
const WRITE_STALL_BUDGET_MS = 2000;
// The write to the host is bounded in wall-clock time as well as by the stall budget: a transport
// that keeps taking one byte between refusals is never "stalled", and a 900-byte deny through it
// took over 45 s in the shim before the shim got the same bound. No retry starts after this many
// ms of uptime - 1.5 s past the supervisor's latest possible deadline, 1.5 s under the host's 35 s.
const WRITE_CEILING_MS = MAX_DEADLINE_MS + SUPERVISOR_MARGIN_MS + 1500;

function shimDeadlineMs(raw) {
  if (raw === undefined || raw.trim() === "") return DEFAULT_DEADLINE_MS;
  const parsed = Number(raw);
  if (!Number.isInteger(parsed) || parsed < MIN_DEADLINE_MS || parsed > MAX_DEADLINE_MS) {
    // The shim denies an invalid value at once; the supervisor only needs an upper bound.
    return MAX_DEADLINE_MS;
  }
  return parsed;
}

function serializeDeny(reason) {
  return (
    JSON.stringify({
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: reason,
      },
    }) + "\n"
  );
}

// The deny the child produced, or null. Exactly one PreToolUse deny object with a string reason;
// the reason is re-serialized so no sibling key the child wrote reaches the host.
function childDeny(stdout) {
  const trimmed = stdout.trim();
  if (!trimmed.startsWith("{") || trimmed.includes("\n")) return null;
  try {
    const out = JSON.parse(trimmed)?.hookSpecificOutput;
    if (
      typeof out === "object" &&
      out !== null &&
      out.hookEventName === "PreToolUse" &&
      out.permissionDecision === "deny" &&
      typeof out.permissionDecisionReason === "string"
    ) {
      const text = serializeDeny(out.permissionDecisionReason);
      // The shim already bounds its deny; a child that did not is not trusted with the host's pipe.
      return Buffer.byteLength(text, "utf8") <= MAX_DENY_BYTES ? text : null;
    }
  } catch {
    // not a decision
  }
  return null;
}

// The supervisor's deadline, in ms of this process's uptime.
const DEADLINE_AT_MS = shimDeadlineMs(process.env.ATBASH_HOOK_DEADLINE_MS) + SUPERVISOR_MARGIN_MS;

let decided = false;
let child = null;
let deadlineTimer = null;

function uptimeMs() {
  return Math.ceil(process.uptime() * 1000);
}

function writeAllSync(text) {
  // Every byte or an error, retried on EAGAIN without outliving the host's timeout (the shim's
  // writeDecisionSync, without its in-process adversary handling: no bundle runs here). The
  // first attempt always happens; retries stop at the stall budget or at the give-up: 1.5 s past
  // this run's deadline, or one stall budget after the first attempt if that is later, and never
  // past WRITE_CEILING_MS.
  const buffer = Buffer.from(text, "utf8");
  let offset = 0;
  let attempts = 0;
  const firstAttempt = uptimeMs();
  const giveUp = Math.min(
    WRITE_CEILING_MS,
    Math.max(DEADLINE_AT_MS + 1500, firstAttempt + WRITE_STALL_BUDGET_MS),
  );
  let lastProgress = firstAttempt;
  while (offset < buffer.length) {
    if (attempts > 0) {
      const now = uptimeMs();
      if (now >= giveUp || now - lastProgress >= WRITE_STALL_BUDGET_MS) {
        throw Object.assign(new Error("the decision could not be written"), { code: "ETIMEDOUT" });
      }
    }
    attempts += 1;
    try {
      const written = writeSync(1, buffer, offset, buffer.length - offset);
      if (!Number.isInteger(written) || written < 0 || written > buffer.length - offset) {
        throw Object.assign(new Error("impossible byte count"), { code: "EIO" });
      }
      if (written > 0) {
        offset += written;
        lastProgress = uptimeMs();
        continue;
      }
    } catch (error) {
      if (!(error && error.code === "EAGAIN")) throw error;
    }
    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, WRITE_RETRY_WAIT_MS);
  }
}

function finish(text) {
  if (decided) return;
  decided = true;
  if (deadlineTimer !== null) clearTimeout(deadlineTimer);
  if (child !== null && child.exitCode === null && child.signalCode === null) {
    try {
      child.kill("SIGKILL");
    } catch {
      // already gone
    }
  }
  if (text === "") {
    process.exit(0);
    return;
  }
  try {
    writeAllSync(text);
    process.exit(0);
  } catch {
    // stdout is gone: a blocking exit (Claude Code), never 0 with an empty, permit-shaped stdout.
    try {
      writeSync(2, "Atbash ERROR: the decision could not be delivered to the host.\n");
    } catch {
      // nothing left to report to
    }
    process.exit(2);
  }
}

function deny(reason) {
  finish(serializeDeny(reason));
}

// Last word: a supervisor that ends any other way still denies.
process.on("uncaughtException", () => deny("Atbash ERROR: the hook supervisor failed."));
process.on("exit", () => {
  if (decided) return;
  decided = true;
  try {
    writeAllSync(serializeDeny("Atbash ERROR: the hook ended without a decision."));
    process.exitCode = 0;
  } catch {
    process.exitCode = 2;
  }
});

// Armed first, before the child exists: the clock counts from this process's start.
deadlineTimer = setTimeout(
  () => deny("Atbash ERROR: the safety check did not finish before the host's hook timeout."),
  Math.max(0, DEADLINE_AT_MS - uptimeMs()),
);

try {
  child = spawn(process.execPath, [path.join(__dirname, "pre-tool-use-shim.cjs")], {
    env: { ...process.env, ATBASH_HOOK_PERMIT_FD: "3" },
    stdio: ["pipe", "pipe", "pipe", "pipe"],
    windowsHide: true,
  });
} catch {
  deny("Atbash ERROR: the hook runtime could not start.");
}

if (!decided) {
  const chunks = [];
  let size = 0;
  let overflow = false;
  child.on("error", () => deny("Atbash ERROR: the hook runtime could not start."));
  child.stdout.on("data", (chunk) => {
    size += chunk.length;
    if (size > MAX_CHILD_STDOUT_BYTES) overflow = true;
    else chunks.push(chunk);
  });
  let sign = "";
  child.stdio[3].on("data", (chunk) => {
    if (sign.length <= PERMIT_SIGN.length) sign += chunk.toString("utf8");
  });
  child.stdio[3].on("error", () => {});
  let relayed = 0;
  child.stderr.on("data", (chunk) => {
    if (relayed >= MAX_STDERR_RELAY_BYTES) return;
    const room = MAX_STDERR_RELAY_BYTES - relayed;
    relayed += Math.min(chunk.length, room);
    try {
      writeSync(2, chunk.subarray(0, room));
      if (relayed >= MAX_STDERR_RELAY_BYTES) {
        writeSync(2, "\n[Atbash: further hook log lines were dropped]\n");
      }
    } catch {
      // the transcript is optional; the decision is on stdout
    }
  });
  child.stderr.on("error", () => {});
  child.stdout.on("error", () => {});
  child.stdin.on("error", () => {});
  // The host's tool-call payload, passed through unchanged.
  process.stdin.on("error", () => child.stdin.end());
  process.stdin.pipe(child.stdin);
  child.on("close", (code, signal) => {
    if (decided) return;
    const stdout = Buffer.concat(chunks).toString("utf8");
    if (code === 0 && signal === null && !overflow) {
      if (stdout === "" && sign === PERMIT_SIGN) {
        finish("");
        return;
      }
      const forwarded = childDeny(stdout);
      if (forwarded !== null) {
        finish(forwarded);
        return;
      }
    }
    deny("Atbash ERROR: the hook ended without a usable decision.");
  });
}

SHA-256: c6fe2773b564a791f4b0191242d7e24f5a05c0018794e3697fcb65bdc0748f5d