faberun 0.3.0

package/src/host/tool-policy-decisions.mjs

@@ -0,0 +1,341 @@
+/**
+ * The three PreToolUse decisions the tool policy hook carries but does not
+ * yet apply: a write outside the declared scope, a whole-file read above the
+ * line threshold, and the same read done through `Bash` (`cat`/`less`/`more`,
+ * or `head`/`tail` with no explicit limit). Kept out of tool-policy-hook.mjs
+ * so that module stays the wiring (argv, settings, event dispatch) and this
+ * one stays the judgment calls, each a pure function of policy and payload.
+ *
+ * The two read decisions only deny what they can measure: a file that is
+ * missing, unreadable, or not a regular file passes through, because the hook
+ * must never be the reason a model cannot see the tool's own error. The write
+ * decision is different in kind -- scope membership is a fact about the path,
+ * not about the disk -- so it judges a target that does not exist yet exactly
+ * like one that does. Creating a new file outside the declared scope is the
+ * ordinary violation, and skipping it would leave the decision firing only on
+ * overwrites.
+ *
+ * A write made through `Bash` (`>`, `sed -i`, `tee`) is deliberately not
+ * caught here: sniffing shell syntax for a write is a race no static read of
+ * `command` wins, and the post-hoc scope gate in `engine/scope.mjs` already
+ * catches the effect once the attempt completes.
+ */
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { closeSync, fstatSync, openSync, readSync, realpathSync } from "node:fs";
+
+/**
+ * Tool name to the payload field carrying the path it would write.
+ *
+ * A tool that is not a key here is not judged at all, and Claude Code reads a
+ * hook that says nothing as an allow. That makes the map the enforcement
+ * boundary rather than a lookup table, so `test/host/tool-policy.test.mjs`
+ * pins it against the tool list the adapter actually offers: adding a
+ * write-capable tool to `DEFAULT_CLAUDE_TOOLS` without adding it here fails
+ * the suite instead of silently opening the scope.
+ */
+export const WRITE_SCOPE_FIELDS = { Write: "file_path", Edit: "file_path", NotebookEdit: "notebook_path" };
+
+/** Tools the adapter offers that cannot write, so their absence above is correct. */
+export const READ_ONLY_TOOLS = new Set(["Read", "Bash", "Glob", "Grep", "WebFetch", "WebSearch", "TodoWrite", "Task"]);
+
+/** Bash commands that read a whole file by default. */
+const WHOLE_FILE_READERS = new Set(["cat", "less", "more"]);
+
+/** Bash commands that read a whole file only when given no explicit limit. */
+const BOUNDED_BY_DEFAULT_READERS = new Set(["head", "tail"]);
+
+/** A command containing any of these is a pipeline, redirection or chain: the named file is a filter's input, not read-tool evidence. */
+const SHELL_COMPOSITION_TOKENS = ["|", ">>", ">", "<", "&&", "||", ";"];
+
+/**
+ * DECISION 1: deny a `Write`, `Edit`, or `NotebookEdit` call whose target path
+ * is neither a declared write file nor beneath a declared write root. An empty
+ * scope (no writeFiles and no writeRoots) is the absence of a declared scope,
+ * not a closed one, and denies nothing. Existence is not consulted: a path is
+ * in the declared scope or it is not, and a file the attempt is about to
+ * create is exactly the case worth catching before it exists.
+ *
+ * @param {{workspace: string|null, writeFiles: string[], writeRoots: string[]}} policy
+ * @param {{tool_name?: unknown, tool_input?: unknown}} payload
+ * @returns {{hookSpecificOutput: Record<string, unknown>}|null}
+ */
+export function writeScopeDecision(policy, payload) {
+  const name = typeof payload?.tool_name === "string" ? payload.tool_name : "";
+  const field = /** @type {Record<string, string>} */ (WRITE_SCOPE_FIELDS)[name];
+  if (!field) return null;
+  const writeFiles = policy.writeFiles ?? [];
+  const writeRoots = policy.writeRoots ?? [];
+  if (!writeFiles.length && !writeRoots.length) return null;
+  const workspace = typeof policy.workspace === "string" ? policy.workspace : "";
+  if (!workspace) return null;
+  const input = payload?.tool_input;
+  const rawPath = input && typeof input === "object" ? /** @type {Record<string, unknown>} */ (input)[field] : undefined;
+  if (typeof rawPath !== "string" || !rawPath) return null;
+  // Both spellings are offered to the match: the path as declared, and the
+  // path the filesystem actually reaches. A symlink pointing elsewhere inside
+  // the workspace is a legitimate scope (git reports the target's spelling,
+  // which is why `repo/workspace.mjs` accepts both too); one pointing outside
+  // is the escape below.
+  const spellings = workspaceSpellings(workspace, rawPath);
+  if (spellings.reachesWorkspace && spellings.readings.some((rel) => inDeclaredScope(rel, writeFiles, writeRoots))) return null;
+  return denyPreTool(writeScopeDenialReason(writeFiles, writeRoots));
+}
+
+/**
+ * Whether one workspace-relative spelling sits in the declared scope.
+ * Comparison is Unicode-normalized because a macOS path round-trips between
+ * NFC and NFD and a worker that renormalizes a filename it is entitled to
+ * write should not meet an opaque denial. A declared root keeps matching with
+ * a trailing slash, which is an easy thing to type into a contract and used to
+ * break every write under that root.
+ *
+ * @param {string|null} rel
+ * @param {string[]} writeFiles
+ * @param {string[]} writeRoots
+ * @returns {boolean}
+ */
+function inDeclaredScope(rel, writeFiles, writeRoots) {
+  if (rel === null) return false;
+  const target = rel.normalize("NFC");
+  if (writeFiles.some((file) => file.normalize("NFC") === target)) return true;
+  return writeRoots.some((declared) => {
+    const root = declared.normalize("NFC").replace(/\/+$/u, "");
+    return root !== "" && (target === root || target.startsWith(`${root}/`));
+  });
+}
+
+/**
+ * @param {string[]} writeFiles
+ * @param {string[]} writeRoots
+ * @returns {string}
+ */
+function writeScopeDenialReason(writeFiles, writeRoots) {
+  const declared = [...writeFiles, ...writeRoots.map((root) => `${root}/`)];
+  const shown = declared.slice(0, 12);
+  const omitted = declared.length - shown.length;
+  const remainder = omitted > 0 ? ` (and ${omitted} more not shown)` : "";
+  return `write denied: this path is outside the declared write scope. Declared write paths: ${shown.join(", ")}${remainder}. Write only to one of those.`;
+}
+
+/**
+ * DECISION 2: deny a `Read` call that would read an entire file above
+ * `policy.maxReadLines` with neither `offset` nor `limit`. A file that cannot
+ * be measured -- missing, unreadable, not a regular file -- passes through.
+ *
+ * @param {{maxReadLines: number|null}} policy
+ * @param {{tool_name?: unknown, tool_input?: unknown}} payload
+ * @returns {{hookSpecificOutput: Record<string, unknown>}|null}
+ */
+export function readThresholdDecision(policy, payload) {
+  if (typeof payload?.tool_name !== "string" || payload.tool_name !== "Read") return null;
+  const maxReadLines = policy.maxReadLines;
+  if (typeof maxReadLines !== "number" || maxReadLines <= 0) return null;
+  const input = payload?.tool_input;
+  if (!input || typeof input !== "object") return null;
+  const record = /** @type {Record<string, unknown>} */ (input);
+  if (record.offset !== undefined || record.limit !== undefined) return null;
+  const rawPath = record.file_path;
+  if (typeof rawPath !== "string" || !rawPath) return null;
+  const lines = countLines(rawPath);
+  if (lines === null || lines <= maxReadLines) return null;
+  return denyPreTool(readThresholdDenialReason(lines, maxReadLines));
+}
+
+/**
+ * DECISION 3: deny the same whole-file read done through `Bash` -- a single
+ * `cat`/`less`/`more` invocation, or `head`/`tail` with no explicit limit --
+ * over a file above the threshold. A command carrying a pipe, redirection, or
+ * chain passes without analysis: the named file is then a filter's input, not
+ * evidence entering the model's context.
+ *
+ * @param {{maxReadLines: number|null}} policy
+ * @param {{tool_name?: unknown, tool_input?: unknown}} payload
+ * @returns {{hookSpecificOutput: Record<string, unknown>}|null}
+ */
+export function bashReadDecision(policy, payload) {
+  if (typeof payload?.tool_name !== "string" || payload.tool_name !== "Bash") return null;
+  const maxReadLines = policy.maxReadLines;
+  if (typeof maxReadLines !== "number" || maxReadLines <= 0) return null;
+  const input = payload?.tool_input;
+  const command = input && typeof input === "object" ? /** @type {Record<string, unknown>} */ (input).command : undefined;
+  if (typeof command !== "string" || !command.trim()) return null;
+  if (SHELL_COMPOSITION_TOKENS.some((token) => command.includes(token))) return null;
+  const tokens = command.trim().split(/\s+/u);
+  const program = basename(tokens[0] ?? "");
+  const args = tokens.slice(1);
+  if (WHOLE_FILE_READERS.has(program)) {
+    return bashTargetDenial(args, maxReadLines);
+  }
+  if (BOUNDED_BY_DEFAULT_READERS.has(program) && !hasExplicitLimit(args)) {
+    return bashTargetDenial(args, maxReadLines);
+  }
+  return null;
+}
+
+/**
+ * @param {string[]} args
+ * @param {number} maxReadLines
+ * @returns {{hookSpecificOutput: Record<string, unknown>}|null}
+ */
+function bashTargetDenial(args, maxReadLines) {
+  const target = [...args].reverse().find((token) => !token.startsWith("-"));
+  if (!target) return null;
+  const lines = countLines(target);
+  if (lines === null || lines <= maxReadLines) return null;
+  return denyPreTool(readThresholdDenialReason(lines, maxReadLines, true));
+}
+
+/**
+ * @param {string[]} args
+ * @returns {boolean}
+ */
+function hasExplicitLimit(args) {
+  return args.some((arg) => arg === "-n" || arg === "-c" || /^-[nc]\d+$/u.test(arg) || /^-\d+$/u.test(arg));
+}
+
+/**
+ * @param {number} lines
+ * @param {number} maxReadLines
+ * @param {boolean} [viaBash]
+ * @returns {string}
+ */
+function readThresholdDenialReason(lines, maxReadLines, viaBash = false) {
+  const retry = viaBash
+    ? "rerun with an explicit limit (head -n, tail -n) or use the Read tool with an offset and limit"
+    : "reread it with an offset and limit instead of the whole file";
+  return `read denied: this file has ${lines} lines, above the ${maxReadLines}-line read threshold; ${retry}.`;
+}
+
+/**
+ * Where a target path actually lands, and the workspace-relative spellings it
+ * can be judged under: the one the caller wrote, and the one the filesystem
+ * reaches through any symlink on the way. A path the filesystem does not
+ * reach inside the workspace is refused whatever it was spelled as; a path
+ * that does is in scope if either spelling is.
+ *
+ * Lexical containment alone was an escape, reproduced 2026-09-13 against the
+ * real provider: declare `writeRoots: ["src/pkg"]` where `src/pkg` is a
+ * symlink to a directory outside the repository, and `Write` to
+ * `src/pkg/new.txt` passed the prefix test and landed outside the workspace.
+ * The provider's own refusal does not cover it either — that one lstats the
+ * exact target, so a symlinked *intermediate directory* never trips it.
+ *
+ * @param {string} workspace
+ * @param {string} rawPath
+ * @returns {{reachesWorkspace: boolean, readings: (string|null)[]}}
+ */
+function workspaceSpellings(workspace, rawPath) {
+  const root = realPath(workspace) ?? workspace;
+  const absolute = isAbsolute(rawPath) ? rawPath : resolve(workspace, rawPath);
+  const resolved = resolveThroughLinks(absolute);
+  const reached = resolved === null ? null : containedRelativePath(root, resolved);
+  // The declared spelling is measured against both readings of the workspace
+  // root. A caller naming an absolute path uses the root it was handed, which
+  // on macOS is routinely a symlink (`/var` to `/private/var`), and measuring
+  // that against the resolved root alone reads every path as an escape.
+  const declared = containedRelativePath(root, absolute) ?? containedRelativePath(workspace, absolute);
+  return { reachesWorkspace: reached !== null, readings: [declared, reached] };
+}
+
+/**
+ * @param {string} root
+ * @param {string} absolute
+ * @returns {string|null} the forward-slash relative path, or null when it is not inside the root
+ */
+function containedRelativePath(root, absolute) {
+  const rel = relative(root, absolute);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
+  return sep === "\\" ? rel.replaceAll("\\", "/") : rel;
+}
+
+/**
+ * Resolve the longest existing prefix of a path through the filesystem and
+ * re-append the components that do not exist yet, so a file about to be
+ * created is judged at the location it will actually occupy. `null` when
+ * containment cannot be proven — an unreadable component denies rather than
+ * passes, since the whole point is to refuse what cannot be shown to be
+ * inside.
+ *
+ * @param {string} absolute
+ * @returns {string|null}
+ */
+function resolveThroughLinks(absolute) {
+  /** @type {string[]} */
+  const tail = [];
+  let current = absolute;
+  for (;;) {
+    const real = realPath(current);
+    if (real !== null) return tail.length ? resolve(real, ...tail) : real;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    tail.unshift(basename(current));
+    current = parent;
+  }
+}
+
+/** @param {string} path @returns {string|null} */
+function realPath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    // Missing, unreadable, or a non-directory component: the caller walks up
+    // to the nearest existing ancestor, and gives up when there is none.
+    return null;
+  }
+}
+
+/**
+ * Count lines in a file without loading it fully into memory: newline bytes
+ * plus one more line when the file does not end on a newline. `null` means
+ * the path does not exist, is not a regular file, or cannot be read -- the
+ * caller must pass the invocation through rather than fabricate a denial for
+ * evidence it cannot prove.
+ *
+ * @param {string} path
+ * @returns {number|null}
+ */
+function countLines(path) {
+  let fd;
+  try {
+    fd = openSync(path, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const stats = fstatSync(fd);
+    if (!stats.isFile()) return null;
+    if (stats.size === 0) return 0;
+    const buffer = Buffer.alloc(64 * 1024);
+    let lines = 0;
+    let position = 0;
+    let lastByte = -1;
+    while (position < stats.size) {
+      const read = readSync(fd, buffer, 0, buffer.length, position);
+      if (read <= 0) break;
+      for (let index = 0; index < read; index += 1) {
+        if (buffer[index] === 0x0a) lines += 1;
+      }
+      lastByte = buffer[read - 1];
+      position += read;
+    }
+    return lastByte === 0x0a ? lines : lines + 1;
+  } catch {
+    return null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * @param {string} reason
+ * @returns {{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: string}}}
+ */
+function denyPreTool(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+}

package/src/host/tool-policy-hook.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * Repository-owned enforcement hook for the mechanical worker tool policy at
+ * the Claude-compatible CLI boundary (RETROSPECTIVE-2026-08-28 P0.7/P1.1).
+ * The runner registers one command for both events through `--settings`:
+ *
+ * - PreToolUse denies, in order: a `Bash` invocation with `run_in_background:
+ *   true` and the background-output tools; a `Write`/`Edit`/`NotebookEdit`
+ *   outside the declared write scope; a whole-file `Read`, or the same read
+ *   done through `Bash` (`cat`/`less`/`more`, or `head`/`tail` with no
+ *   explicit limit), above `--max-read-lines`. Every denial reason tells the
+ *   model how to retry. The write-scope and read-threshold judgment calls
+ *   live in `tool-policy-decisions.mjs`; this module is the argv wiring and
+ *   event dispatch, not the decisions themselves.
+ * - PostToolUse bounds the textual evidence of a Bash result to at most
+ *   `--max-tool-output-bytes` UTF-8 bytes, keeping head and tail; small
+ *   results are emitted unchanged (no output at all leaves them untouched).
+ *
+ * A write made through `Bash` is not intercepted here: sniffing shell syntax
+ * for a write is a race no static read of `command` wins, and the post-hoc
+ * scope gate in `engine/scope.mjs` already catches the effect once the
+ * attempt completes.
+ *
+ * The settings that wire this hook are installed inline via `--settings` on
+ * every provider invocation; nothing is written to the worktree, so there is
+ * no file to remove when the attempt is sealed.
+ *
+ * Every decision is pure and exported so the settings wiring and the hook
+ * behavior stay testable without a live provider.
+ */
+import { realpathSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { TOOL_OUTPUT_LIMIT_BYTES, truncateToolOutput } from "../harnesses/exec-jsonl/index.mjs";
+import { bashReadDecision, readThresholdDecision, writeScopeDecision } from "./tool-policy-decisions.mjs";
+
+/** Absolute path of this hook, embedded in generated settings. */
+export const HOOK_PATH = fileURLToPath(import.meta.url);
+
+/** Tools whose only purpose is to observe a background invocation. */
+const BACKGROUND_OUTPUT_TOOLS = ["TaskOutput", "BashOutput", "Monitor"];
+
+/** PreToolUse matcher covering every tool the policy may deny. */
+export const PRE_TOOL_MATCHER = ["Bash", ...BACKGROUND_OUTPUT_TOOLS, "Write", "Edit", "NotebookEdit", "Read"].join("|");
+
+/** Standard foreground-only denial; it tells the model how to retry. */
+export const FOREGROUND_ONLY_DENIAL = "background tool invocation denied by the foreground-only tool policy; rerun the tool in the foreground and wait for it to finish";
+
+/** The policy shape as parsed off argv: `workspace` is null when the flag was omitted, unlike the always-populated {@link import("../harnesses/index.mjs").ToolPolicy} the engine builds.
+ * @typedef {{foregroundOnly: boolean, maxToolOutputBytes: number, workspace: string|null, writeFiles: string[], writeRoots: string[], maxReadLines: number|null}} ParsedPolicy
+ */
+
+/**
+ * @param {string[]} argv
+ * @returns {ParsedPolicy}
+ */
+function parsePolicy(argv) {
+  const flags = parseArgs({ args: argv, options: {
+    "foreground-only": { type: "boolean", default: false },
+    "max-tool-output-bytes": { type: "string" },
+    "workspace": { type: "string" },
+    "write-file": { type: "string", multiple: true, default: [] },
+    "write-root": { type: "string", multiple: true, default: [] },
+    "max-read-lines": { type: "string" },
+  } });
+  const raw = Number(flags.values["max-tool-output-bytes"]);
+  const rawMaxReadLines = Number(flags.values["max-read-lines"]);
+  return {
+    foregroundOnly: Boolean(flags.values["foreground-only"]),
+    maxToolOutputBytes: Number.isInteger(raw) && raw > 0 ? raw : TOOL_OUTPUT_LIMIT_BYTES,
+    workspace: typeof flags.values.workspace === "string" ? flags.values.workspace : null,
+    writeFiles: /** @type {string[]} */ (flags.values["write-file"] ?? []),
+    writeRoots: /** @type {string[]} */ (flags.values["write-root"] ?? []),
+    maxReadLines: flags.values["max-read-lines"] === undefined
+      ? null
+      : (Number.isInteger(rawMaxReadLines) && rawMaxReadLines > 0 ? rawMaxReadLines : null),
+  };
+}
+
+/**
+ * The hook command string registered in generated settings, carrying the
+ * policy it enforces as explicit arguments.
+ *
+ * @param {import("../harnesses/index.mjs").ToolPolicy} policy
+ * @returns {string}
+ */
+export function hookCommand(policy) {
+  const argv = [process.execPath, HOOK_PATH];
+  if (policy.foregroundOnly) argv.push("--foreground-only");
+  if (typeof policy.maxToolOutputBytes === "number" && policy.maxToolOutputBytes > 0) {
+    argv.push("--max-tool-output-bytes", String(policy.maxToolOutputBytes));
+  }
+  if (typeof policy.workspace === "string" && policy.workspace) argv.push("--workspace", policy.workspace);
+  for (const file of policy.writeFiles ?? []) argv.push("--write-file", file);
+  for (const root of policy.writeRoots ?? []) argv.push("--write-root", root);
+  if (typeof policy.maxReadLines === "number" && policy.maxReadLines > 0) {
+    argv.push("--max-read-lines", String(policy.maxReadLines));
+  }
+  return argv.map(shellQuote).join(" ");
+}
+
+/**
+ * The Claude-compatible `--settings` payload wiring this hook for the policy:
+ * PreToolUse denial where foreground-only applies, PostToolUse bounding where
+ * a byte limit applies.
+ *
+ * @param {import("../harnesses/index.mjs").ToolPolicy} policy
+ * @returns {{hooks: Record<string, {matcher: string, hooks: {type: "command", command: string}[]}[]>}}
+ */
+export function hookSettings(policy) {
+  /** @type {Record<string, {matcher: string, hooks: {type: "command", command: string}[]}[]>} */
+  const hooks = {};
+  const hasWriteScope = Boolean((policy.writeFiles ?? []).length || (policy.writeRoots ?? []).length);
+  const hasReadThreshold = typeof policy.maxReadLines === "number" && policy.maxReadLines > 0;
+  if (policy.foregroundOnly || hasWriteScope || hasReadThreshold) {
+    hooks.PreToolUse = [{ matcher: PRE_TOOL_MATCHER, hooks: [hookEntry(policy)] }];
+  }
+  if (typeof policy.maxToolOutputBytes === "number" && policy.maxToolOutputBytes > 0) {
+    hooks.PostToolUse = [{ matcher: "Bash", hooks: [hookEntry(policy)] }];
+  }
+  return { hooks };
+}
+
+/**
+ * The mechanical PreToolUse decision: the standard denial when the policy
+ * forbids what the invocation asks for, null when it may run.
+ *
+ * @param {{foregroundOnly: boolean}} policy
+ * @param {{tool_name?: unknown, tool_input?: unknown}} payload
+ * @returns {{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: string}}|null}
+ */
+function preToolUseDecision(policy, payload) {
+  if (policy.foregroundOnly !== true) return null;
+  const name = typeof payload?.tool_name === "string" ? payload.tool_name : "";
+  const input = payload?.tool_input;
+  const backgroundBash = name === "Bash"
+    && Boolean(input) && typeof input === "object"
+    && /** @type {Record<string, unknown>} */ (input).run_in_background === true;
+  if (!backgroundBash && !BACKGROUND_OUTPUT_TOOLS.includes(name)) return null;
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: FOREGROUND_ONLY_DENIAL,
+    },
+  };
+}
+
+/**
+ * Bound the textual evidence of one tool response without changing its shape:
+ * a string stays a string, an object keeps every key, and the retained text
+ * totals at most `maxBytes` UTF-8 bytes. Null means nothing needed bounding.
+ *
+ * @param {number} maxBytes
+ * @param {unknown} toolResponse
+ * @returns {string|Record<string, unknown>|null}
+ */
+function boundedToolOutput(maxBytes, toolResponse) {
+  if (typeof toolResponse === "string") {
+    const bounded = truncateToolOutput(toolResponse, maxBytes);
+    return bounded === toolResponse ? null : bounded;
+  }
+  if (!toolResponse || typeof toolResponse !== "object" || Array.isArray(toolResponse)) return null;
+  const record = /** @type {Record<string, unknown>} */ (toolResponse);
+  const fields = Object.keys(record).filter((key) => typeof record[key] === "string");
+  const sizes = fields.map((key) => Buffer.byteLength(/** @type {string} */ (record[key]), "utf8"));
+  if (sizes.reduce((sum, size) => sum + size, 0) <= maxBytes) return null;
+  const budgets = allocateTextBudgets(sizes, maxBytes);
+  const updated = { ...record };
+  fields.forEach((key, index) => {
+    updated[key] = truncateToolOutput(/** @type {string} */ (record[key]), budgets[index]);
+  });
+  return updated;
+}
+
+/**
+ * Deterministic budget split across textual fields: proportional shares, with
+ * surplus from fields that fit flowing to the fields that do not.
+ *
+ * @param {number[]} sizes
+ * @param {number} maxBytes
+ * @returns {number[]}
+ */
+function allocateTextBudgets(sizes, maxBytes) {
+  const total = sizes.reduce((sum, size) => sum + size, 0);
+  const budgets = sizes.map((size) => Math.floor((size * maxBytes) / total));
+  let surplus = maxBytes - budgets.reduce((sum, budget) => sum + budget, 0);
+  for (let index = 0; index < sizes.length; index += 1) {
+    if (budgets[index] < sizes[index]) continue;
+    surplus += budgets[index] - sizes[index];
+    budgets[index] = sizes[index];
+  }
+  for (let index = 0; index < sizes.length && surplus > 0; index += 1) {
+    const room = sizes[index] - budgets[index];
+    if (room <= 0) continue;
+    budgets[index] += Math.min(room, surplus);
+    surplus -= Math.min(room, surplus);
+  }
+  return budgets;
+}
+
+/**
+ * One hook decision for one parsed payload, or null when the tool result must
+ * pass through untouched. The order among the PreToolUse decisions only
+ * matters for the reason the model reads; foregroundOnly stays first because
+ * it was the first policy this hook enforced.
+ *
+ * @param {ParsedPolicy} policy
+ * @param {unknown} payload
+ * @returns {{hookSpecificOutput: Record<string, unknown>}|null}
+ */
+function hookDecision(policy, payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const record = /** @type {Record<string, unknown>} */ (payload);
+  const event = typeof record.hook_event_name === "string"
+    ? record.hook_event_name
+    : record.tool_response === undefined ? "PreToolUse" : "PostToolUse";
+  if (event === "PreToolUse") {
+    return preToolUseDecision(policy, record)
+      ?? writeScopeDecision(policy, record)
+      ?? readThresholdDecision(policy, record)
+      ?? bashReadDecision(policy, record);
+  }
+  if (event === "PostToolUse") {
+    if (typeof record.tool_name === "string" && record.tool_name !== "Bash") return null;
+    const bounded = boundedToolOutput(policy.maxToolOutputBytes, record.tool_response);
+    return bounded === null ? null : { hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput: bounded } };
+  }
+  return null;
+}
+
+/**
+ * @param {import("../harnesses/index.mjs").ToolPolicy} policy
+ * @returns {{type: "command", command: string}}
+ */
+function hookEntry(policy) {
+  return { type: "command", command: hookCommand(policy) };
+}
+
+/** @param {string} value @returns {string} */
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/** @returns {boolean} */
+function invokedAsScript() {
+  try {
+    return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === HOOK_PATH;
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript()) {
+  const policy = parsePolicy(process.argv.slice(2));
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => { input += chunk; });
+  process.stdin.on("end", () => {
+    // An unparsable payload must never break the provider: decide nothing.
+    let payload = null;
+    try {
+      payload = JSON.parse(input);
+    } catch {
+      // SyntaxError on malformed input leaves payload null; hookDecision then decides nothing, as above.
+    }
+    const decision = hookDecision(policy, payload);
+    if (decision) process.stdout.write(`${JSON.stringify(decision)}\n`);
+  });
+}