@ian-pascoe/pi-guardian 0.0.0

package/src/guardian-settings.ts

@@ -0,0 +1,232 @@
+import type {
+  AgentSession,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import {
+  defineLayeredSettings,
+  type LayeredSettingChange,
+  type LayeredSettingsLayers,
+} from "@ian-pascoe/pi-utils/layered-settings";
+import { Type, type Static } from "typebox";
+import { literalWords } from "./safe-command.js";
+
+/** A Tool Policy: run without review, send to the Guardian, or block outright. */
+export const toolPolicySchema = Type.Union([
+  Type.Literal("allow"),
+  Type.Literal("review"),
+  Type.Literal("deny"),
+]);
+export type ToolPolicy = Static<typeof toolPolicySchema>;
+
+export const thinkingLevelSchema = Type.Union([
+  Type.Literal("off"),
+  Type.Literal("minimal"),
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+  Type.Literal("xhigh"),
+  Type.Literal("max"),
+]);
+export type GuardianThinkingLevel = Static<typeof thinkingLevelSchema>;
+
+const positiveInteger = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+
+/** Authored Guardian options; every key is optional so absent values inherit. */
+export const guardianOptionsSchema = Type.Object(
+  {
+    enabled: Type.Optional(Type.Boolean()),
+    model: Type.Optional(Type.String({ minLength: 1 })),
+    thinkingLevel: Type.Optional(thinkingLevelSchema),
+    /** Per-tool Tool Policies; `null` resets an inherited entry to the built-in default. */
+    tools: Type.Optional(
+      Type.Record(Type.String({ minLength: 1 }), Type.Union([toolPolicySchema, Type.Null()])),
+    ),
+    /** Extra Safe Command prefixes, such as `npm test`; merged across scopes as a union. */
+    safeCommands: Type.Optional(
+      Type.Array(Type.String({ minLength: 1, pattern: "\\S" }), { uniqueItems: true }),
+    ),
+    /** Security Policy added to the Guardian's built-in policy. */
+    policy: Type.Optional(Type.String()),
+    reviewTimeoutMs: Type.Optional(Type.Integer({ minimum: 1, maximum: 2_147_483_647 })),
+    evidenceBudgetTokens: Type.Optional(Type.Union([positiveInteger, Type.Literal("auto")])),
+    onDeny: Type.Optional(Type.Union([Type.Literal("block"), Type.Literal("ask")])),
+    maxConsecutiveRejections: Type.Optional(
+      Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
+    ),
+    /** Ask for a rationale on every review and show allowed reviews in the transcript. */
+    verbose: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+);
+
+/** Authored options; absent values inherit rather than disabling their setting. */
+export type GuardianOptions = Static<typeof guardianOptionsSchema>;
+/** Fully defaulted settings; an absent model follows the Guarded Agent's current model. */
+export interface GuardianConfig {
+  enabled: boolean;
+  model?: string;
+  thinkingLevel: GuardianThinkingLevel;
+  /** Effective Tool Policies after merging every scope's entries. */
+  tools: Record<string, ToolPolicy>;
+  safeCommands: string[];
+  policy: string;
+  reviewTimeoutMs: number;
+  evidenceBudgetTokens: number | "auto";
+  onDeny: "block" | "ask";
+  maxConsecutiveRejections: number;
+  verbose: boolean;
+}
+
+export const guardianSettingScopeSchema = Type.Union([
+  Type.Literal("session"),
+  Type.Literal("global"),
+  Type.Literal("project"),
+]);
+export type GuardianSettingScope = Static<typeof guardianSettingScopeSchema>;
+export const guardianSettingSourceSchema = Type.Union([
+  Type.Literal("default"),
+  guardianSettingScopeSchema,
+]);
+export type GuardianSettingSource = Static<typeof guardianSettingSourceSchema>;
+
+export const guardianDefaults: GuardianConfig = {
+  enabled: true,
+  thinkingLevel: "low",
+  tools: {},
+  safeCommands: [],
+  policy: "",
+  reviewTimeoutMs: 60_000,
+  evidenceBudgetTokens: "auto",
+  onDeny: "block",
+  maxConsecutiveRejections: 3,
+  verbose: false,
+};
+
+/** Pi's branch summarization uses the same fallback for models without a declared window. */
+const fallbackWindow = 128_000;
+const autoEvidenceCeiling = 32_000;
+
+/**
+ * Evidence token budget. `auto` is a quarter of the Guardian model's context window, at most 32K:
+ * every Reviewed Call blocks the agent until its review ends, so evidence stays small.
+ */
+export function evidenceBudget(
+  setting: GuardianConfig["evidenceBudgetTokens"],
+  contextWindow: number | undefined,
+): number {
+  if (setting !== "auto") return contextWindow ? Math.min(setting, contextWindow) : setting;
+  return Math.min(Math.floor((contextWindow || fallbackWindow) / 4), autoEvidenceCeiling);
+}
+
+const layered = defineLayeredSettings({
+  namespace: "guardian",
+  label: "Guardian",
+  schema: guardianOptionsSchema,
+  defaults: guardianDefaults,
+  sessionEntryType: "pi-guardian-settings",
+  merge: {
+    // Each scope adds or replaces entries; `null` drops the inherited entry.
+    tools: (current: GuardianConfig["tools"], next: NonNullable<GuardianOptions["tools"]>) => {
+      const merged = { ...current };
+      for (const [name, policy] of Object.entries(next)) {
+        if (policy === null) delete merged[name];
+        else merged[name] = policy;
+      }
+      return merged;
+    },
+    safeCommands: (current: string[], next: string[]) => [...new Set([...current, ...next])],
+  },
+});
+
+export const guardianOptionKeys = layered.optionKeys;
+
+/**
+ * Reject `safeCommands` entries that could never match: an entry must be literal words, and its
+ * program a bare name, since a command run through a path (`./gradlew`) is never a Safe Command.
+ */
+function checkSafeCommands(
+  options: GuardianOptions,
+  source: GuardianSettingScope,
+): GuardianOptions {
+  for (const [index, entry] of (options.safeCommands ?? []).entries()) {
+    const program = literalWords(entry)?.[0];
+    const problem =
+      program === undefined
+        ? "must be literal words without shell syntax"
+        : /[/\\]/.test(program)
+          ? "must start with a bare program name, not a path"
+          : undefined;
+    if (problem)
+      throw new Error(
+        `Invalid ${source} Guardian settings/safeCommands/${index}: Safe Command ${JSON.stringify(entry)} ${problem}`,
+      );
+  }
+  return options;
+}
+
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- SAFETY: Native settings and command input contain arbitrary authored JSON; the shared layered-settings schema check validates it before use.
+export function parseGuardianOptions(value: unknown, source: GuardianSettingScope) {
+  return checkSafeCommands(layered.parseOptions(value, source), source);
+}
+
+/** Reject inherited or unknown property names before applying an authored change. */
+export function guardianOptionKey(input: string): keyof GuardianOptions {
+  return layered.optionKey(input);
+}
+
+/** Replay only the selected branch's last complete override snapshot. */
+export function readGuardianOverrides(manager: Pick<SessionManager, "getBranch">): GuardianOptions {
+  return layered.readOverrides(manager);
+}
+
+/** Authored scopes cached at startup/reload and updated after this extension's own writes. */
+export type GuardianLayers = LayeredSettingsLayers<GuardianOptions>;
+/** A validated authored mutation, independent of its persistence scope. */
+export type GuardianChange = LayeredSettingChange<GuardianOptions>;
+/** An applied change as recorded for confirmation; `options` is empty when the key inherits. */
+export const guardianAppliedChangeSchema = Type.Object({
+  scope: guardianSettingScopeSchema,
+  key: Type.KeyOf(guardianOptionsSchema),
+  options: guardianOptionsSchema,
+});
+export type GuardianAppliedChange = Static<typeof guardianAppliedChangeSchema>;
+
+/** Read Pi's stored layers, preserving configuration failures until corrected. */
+export function readGuardianLayers(manager: SettingsManager): GuardianLayers {
+  const layers = layered.readLayers(manager);
+  for (const scope of ["global", "project"] as const) {
+    const layer = layers[scope];
+    if (layer instanceof Error) continue;
+    try {
+      checkSafeCommands(layer, scope);
+    } catch (cause) {
+      layers[scope] = cause instanceof Error ? cause : new Error(String(cause));
+    }
+  }
+  return layers;
+}
+
+/** Effective settings with the scope that supplied each key. */
+export interface ResolvedGuardianSettings {
+  settings: GuardianConfig;
+  sources: Record<string, GuardianSettingSource>;
+}
+
+/** Resolve stored scopes: default < global < trusted project < session. */
+export function readGuardianSettings(
+  session: Pick<AgentSession, "settingsManager" | "sessionManager">,
+  authored = readGuardianLayers(session.settingsManager),
+): ResolvedGuardianSettings {
+  return layered.readSettings(session, authored);
+}
+
+/** Write one change to Pi's global or trusted project settings document. */
+export function writeGuardianSettings(
+  manager: SettingsManager,
+  scope: "global" | "project",
+  change: GuardianChange,
+  isCurrent: () => boolean,
+): Promise<GuardianOptions | undefined> {
+  return layered.writeSettings(manager, scope, change, isCurrent);
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./guardian-extension.js";

package/src/safe-command.ts

@@ -0,0 +1,147 @@
+/**
+ * Safe Command recognition for `bash`. Deliberately conservative: anything this module cannot
+ * read as one simple command of literal words is not a Safe Command and goes to the Guardian.
+ */
+
+/**
+ * Characters that make a command more than one simple command of literal words: pipes,
+ * redirection, chaining, background jobs, subshells, grouping, command/process substitution,
+ * variable/arithmetic/brace/history expansion, globbing, comments, and escapes.
+ */
+const shellSyntax = /[|&;<>()$`\\*?[\]{}!#^]/;
+/** Tilde expansion: `~` starting a word or following `=` or `:` (`HEAD~1` stays literal). */
+const tildeExpansion = /(?:^|[\s=:])~/;
+// oxlint-disable-next-line no-control-regex -- Control characters (including newlines) are exactly what this rejects.
+const controlCharacters = /[\u0000-\u0008\u000a-\u001f\u007f-\u009f\u2028\u2029]/;
+
+/** Split a command into literal words; `undefined` when it is not one simple command. */
+export function literalWords(command: string): string[] | undefined {
+  if (controlCharacters.test(command) || shellSyntax.test(command) || tildeExpansion.test(command))
+    return undefined;
+  const words: string[] = [];
+  let word: string | undefined;
+  let quote: "'" | '"' | undefined;
+  for (const character of command) {
+    if (quote) {
+      if (character === quote) quote = undefined;
+      else word = (word ?? "") + character;
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+      word ??= "";
+      continue;
+    }
+    if (character === " " || character === "\t") {
+      if (word !== undefined) words.push(word);
+      word = undefined;
+      continue;
+    }
+    word = (word ?? "") + character;
+  }
+  if (quote) return undefined;
+  if (word !== undefined) words.push(word);
+  return words.length ? words : undefined;
+}
+
+/** Validates a built-in safe program's arguments; `true` when they cannot cause side effects. */
+type ArgumentCheck = (args: readonly string[]) => boolean;
+
+const anyArguments: ArgumentCheck = () => true;
+const rejectOptions =
+  (...forbidden: string[]): ArgumentCheck =>
+  (args) =>
+    !args.some((arg) => forbidden.some((option) => arg === option || arg.startsWith(`${option}=`)));
+
+/** `find` actions that execute programs, delete files, or write output files. */
+const findActions = new Set([
+  "-exec",
+  "-execdir",
+  "-ok",
+  "-okdir",
+  "-delete",
+  "-fprint",
+  "-fprint0",
+  "-fprintf",
+  "-fls",
+]);
+
+/** `git log`, `diff` and `show` options that write files or run configured external programs. */
+const gitOutputOptions = rejectOptions("--output", "--ext-diff", "--textconv");
+/** `git branch` options that only list branches; any other word could create or delete one. */
+const gitBranchListing = new Set([
+  "-a",
+  "-r",
+  "-v",
+  "-vv",
+  "-l",
+  "--list",
+  "--all",
+  "--remotes",
+  "--verbose",
+  "--show-current",
+  "--no-color",
+  "--color",
+]);
+const gitSubcommands = new Map<string, ArgumentCheck>([
+  ["status", anyArguments],
+  ["log", gitOutputOptions],
+  ["diff", gitOutputOptions],
+  ["show", gitOutputOptions],
+  ["branch", (args) => args.every((arg) => gitBranchListing.has(arg))],
+  ["rev-parse", anyArguments],
+]);
+
+/** Built-in safe programs and their argument checks. */
+const builtInPrograms = new Map<string, ArgumentCheck>([
+  ["ls", anyArguments],
+  ["pwd", anyArguments],
+  ["cat", anyArguments],
+  ["head", anyArguments],
+  ["tail", anyArguments],
+  ["wc", anyArguments],
+  ["echo", anyArguments],
+  ["stat", anyArguments],
+  ["du", anyArguments],
+  ["df", anyArguments],
+  ["basename", anyArguments],
+  ["dirname", anyArguments],
+  ["realpath", anyArguments],
+  ["which", anyArguments],
+  ["whoami", anyArguments],
+  ["uname", anyArguments],
+  ["grep", anyArguments],
+  // `--pre` and `--hostname-bin` run arbitrary programs.
+  ["rg", rejectOptions("--pre", "--pre-glob", "--hostname-bin")],
+  ["find", (args) => !args.some((arg) => findActions.has(arg))],
+  // Global options such as `-c core.pager=…` or `-C dir` must not precede the subcommand.
+  [
+    "git",
+    ([subcommand, ...args]) => {
+      const check = subcommand === undefined ? undefined : gitSubcommands.get(subcommand);
+      return check ? check(args) : false;
+    },
+  ],
+]);
+
+/** The built-in safe program names, for documentation and status. */
+export const builtInSafePrograms: readonly string[] = [...builtInPrograms.keys()];
+
+/**
+ * Whether `command` is a Safe Command: one simple command of literal words whose program is a
+ * built-in safe program with side-effect-free arguments, or whose leading words match one of the
+ * configured `safeCommands` prefixes (for example `npm test`).
+ */
+export function isSafeCommand(command: string, configured: readonly string[] = []): boolean {
+  const words = literalWords(command);
+  const program = words?.[0];
+  if (!words || program === undefined) return false;
+  // An environment assignment (`PAGER=x git log`) or a path (`./ls`) is not a known program.
+  if (program.includes("=") || program.includes("/") || program === "") return false;
+  for (const entry of configured) {
+    const prefix = literalWords(entry);
+    if (prefix?.length && prefix.every((word, index) => words[index] === word)) return true;
+  }
+  const check = builtInPrograms.get(program);
+  return check ? check(words.slice(1)) : false;
+}

package/src/sensitive-paths.ts

@@ -0,0 +1,205 @@
+import { lstatSync, readlinkSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Where Sensitive Paths are judged from. */
+export interface SensitivePathContext {
+  /** Workspace root: the Guarded Agent's working directory. */
+  cwd: string;
+  /** Pi configuration and session locations, sensitive wherever they are. */
+  piDirectories: readonly string[];
+  /**
+   * Files and directories of resources Pi loaded into the Guarded Agent (context files, Skills,
+   * prompt templates, extensions), sensitive wherever they are: they are trusted instructions
+   * or code.
+   */
+  loadedResources?: readonly string[];
+  /** The user's home directory; defaults to `os.homedir()`. */
+  home?: string;
+  /** Defaults to `process.platform`. */
+  platform?: NodeJS.Platform;
+}
+
+// Pi's own path normalization replaces these with ordinary spaces before resolving.
+const unicodeSpaces = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+/** Resolve a tool path argument the way Pi's file tools do, without touching the file system. */
+export function resolveToolPath(input: string, cwd: string): string {
+  let normalized = input.replace(unicodeSpaces, " ");
+  if (normalized.startsWith("@")) normalized = normalized.slice(1);
+  if (normalized === "~") normalized = homedir();
+  else if (normalized.startsWith("~/")) normalized = join(homedir(), normalized.slice(2));
+  else if (normalized.startsWith("file://")) normalized = fileURLToPath(normalized);
+  return isAbsolute(normalized) ? resolve(normalized) : resolve(cwd, normalized);
+}
+
+/**
+ * Resolve symlinks in the longest existing ancestor; the missing remainder stays lexical. A
+ * dangling symlink is followed to its target, so a link to a missing `.git` still counts.
+ */
+function realPath(path: string, depth = 0): string {
+  const missing: string[] = [];
+  let current = path;
+  for (;;) {
+    try {
+      return join(realpathSync.native(current), ...missing.toReversed());
+    } catch {
+      // Not resolvable as a whole; try a dangling link, then the parent.
+    }
+    try {
+      if (depth < 32 && lstatSync(current).isSymbolicLink()) {
+        const target = resolve(dirname(current), readlinkSync(current));
+        return realPath(join(target, ...missing.toReversed()), depth + 1);
+      }
+    } catch {
+      // Missing component: keep walking up.
+    }
+    const parent = dirname(current);
+    if (parent === current) return path;
+    missing.push(basename(current));
+    current = parent;
+  }
+}
+
+/** `path`'s components below `root`, or `undefined` when it lies outside it. */
+function within(path: string, root: string): string[] | undefined {
+  const relation = relative(root, path);
+  if (relation === "") return [];
+  if (relation === ".." || relation.startsWith(`..${sep}`) || isAbsolute(relation))
+    return undefined;
+  return relation.split(sep);
+}
+
+/** Context files Pi loads from the working directory and its ancestors, in any case. */
+const contextFileNames = new Set(["agents.md", "agents.override.md", "claude.md"]);
+
+/**
+ * Locations under the home directory where a change persists beyond the session: shell startup
+ * files, credentials, user configuration, and programs on `PATH`. Judged wherever the workspace is.
+ */
+const homePersistence = new Set([
+  ".bashrc",
+  ".bash_profile",
+  ".bash_login",
+  ".bash_logout",
+  ".profile",
+  ".zshrc",
+  ".zprofile",
+  ".zshenv",
+  ".zlogin",
+  ".zlogout",
+  ".ssh",
+  ".gnupg",
+  ".aws",
+  ".azure",
+  ".config",
+  ".gitconfig",
+  ".git-credentials",
+  ".npmrc",
+  ".yarnrc",
+  ".pypirc",
+  ".netrc",
+  ".docker",
+  ".kube",
+]);
+
+/** Why a path below the home directory is a persistence or credential location. */
+function homeLocation(components: readonly string[]): string | undefined {
+  const [first = "", second = ""] = components.map((component) => component.toLowerCase());
+  const persistent =
+    homePersistence.has(first) ||
+    (first === ".local" && second === "bin") ||
+    (first === "library" && second === "launchagents");
+  return persistent
+    ? `a shell startup, credential, or persistence location in the home directory (${components.slice(0, first === ".local" || first === "library" ? 2 : 1).join("/")})`
+    : undefined;
+}
+
+/**
+ * Components inside the workspace whose change can weaken Guardian, expose secrets, alter
+ * trusted instructions, or run code later: version control, secrets, Pi and agent
+ * configuration, context files, git hooks, CI workflows, and editor tasks.
+ */
+function sensitiveComponent(components: readonly string[]): string | undefined {
+  for (const [index, component] of components.entries()) {
+    const name = component.toLowerCase();
+    if (name === ".git") return "version-control metadata (.git)";
+    if (name === ".pi") return "Pi configuration (.pi)";
+    if (name === ".agents") return "agent Skills and configuration (.agents)";
+    if (name.startsWith(".env")) return `a secret or environment file (${component})`;
+    if (name === ".husky") return "git hooks (.husky)";
+    if (name === ".vscode") return "editor tasks and settings (.vscode)";
+    if (name === ".github" && components[index + 1]?.toLowerCase() === "workflows")
+      return "CI workflows (.github/workflows)";
+  }
+  const last = components.at(-1)?.toLowerCase();
+  if (last && contextFileNames.has(last))
+    return `a context file Pi loads as instructions (${components.at(-1)})`;
+  return undefined;
+}
+
+/** A path in every spelling: as given and with symlinks resolved. */
+interface Spelled {
+  roots: readonly string[];
+  piDirectories: readonly string[];
+  resources: readonly string[];
+  homes: readonly string[];
+}
+
+/** Why `path` is sensitive. */
+function judge(path: string, where: Spelled): string | undefined {
+  if (where.piDirectories.some((directory) => within(path, directory)))
+    return "Pi's agent configuration or session files";
+  if (where.resources.some((resource) => within(path, resource)))
+    return "a context file, Skill, prompt template, or extension Pi loaded";
+  if (where.homes.some((home) => where.roots.some((root) => within(home, root))))
+    return "the workspace root contains the home directory, so every file is reviewed";
+  for (const home of where.homes) {
+    const below = within(path, home);
+    const reason = below && homeLocation(below);
+    if (reason) return reason;
+  }
+  const components = where.roots
+    .map((root) => within(path, root))
+    .find((found) => found !== undefined);
+  if (!components) return "outside the workspace root";
+  return sensitiveComponent(components);
+}
+
+/** A file reachable through more than one hard link: editing it in place changes the others. */
+function hardLinked(path: string): boolean {
+  try {
+    const stats = statSync(path);
+    return stats.isFile() && stats.nlink > 1;
+  } catch {
+    return false;
+  }
+}
+
+/** Windows path forms (backslashes, drive letters, UNC) that Guardian does not judge. */
+const windowsPathForm = /\\|^[A-Za-z]:/;
+
+/**
+ * Why modifying `input` is sensitive, or `undefined` for an ordinary workspace path. Judged on
+ * both the lexical path and the path with symlinks resolved; either being sensitive is enough.
+ */
+export function sensitivePathReason(
+  input: string,
+  context: SensitivePathContext,
+): string | undefined {
+  if ((context.platform ?? process.platform) === "win32" && windowsPathForm.test(input))
+    return "a Windows path form Guardian does not judge";
+  const lexical = resolveToolPath(input, context.cwd);
+  const spellings = (path: string) => [...new Set([resolve(path), realPath(resolve(path))])];
+  const where: Spelled = {
+    roots: spellings(context.cwd),
+    piDirectories: context.piDirectories.flatMap(spellings),
+    resources: (context.loadedResources ?? []).flatMap(spellings),
+    homes: spellings(context.home ?? homedir()),
+  };
+  const targets = spellings(lexical);
+  if (targets.some(hardLinked))
+    return "a file with more than one hard link, so editing it changes another path too";
+  return targets.map((path) => judge(path, where)).find((reason) => reason !== undefined);
+}

package/src/tool-policy.ts

@@ -0,0 +1,94 @@
+import type { CustomToolCallEvent, ToolAnnotations } from "@earendil-works/pi-coding-agent";
+import { isSafeCommand } from "./safe-command.js";
+import { sensitivePathReason, type SensitivePathContext } from "./sensitive-paths.js";
+import type { ToolPolicy } from "./guardian-settings.js";
+
+/** Which rule supplied a call's Tool Policy, in precedence order. */
+export type ToolPolicySource = "setting" | "default" | "annotation" | "fallback";
+
+/** A Tool Policy resolved for one call, with why. */
+export interface ResolvedToolPolicy {
+  policy: ToolPolicy;
+  source: ToolPolicySource;
+  /** Why a built-in default sends this particular call to review. */
+  detail?: string;
+}
+
+/** Tools whose calls run without review by default. */
+export const allowedByDefault: readonly string[] = [
+  "read",
+  "grep",
+  "find",
+  "ls",
+  "codemode",
+  "tool_search",
+  "todo",
+  "web_search",
+  // Context Management: session-local notes, journal reads, and handoffs.
+  "context_notes",
+  "context_history",
+  "context_rollover",
+];
+/** Tools reviewed by default regardless of their annotations. */
+export const reviewedByDefault: readonly string[] = [
+  "terminal_start",
+  "terminal_send",
+  "powershell",
+];
+
+/** Everything Tool Policy resolution reads for one call. */
+export interface ToolPolicyInput {
+  toolName: string;
+  /** The call's arguments after earlier `tool_call` handlers ran. */
+  input: CustomToolCallEvent["input"];
+  /** Configured Tool Policies (`tools` setting), merged across scopes. */
+  configured: Readonly<Record<string, ToolPolicy>>;
+  /** Configured Safe Command prefixes (`safeCommands` setting). */
+  safeCommands: readonly string[];
+  /** The tool's author-supplied annotations, if any. */
+  annotations: ToolAnnotations | undefined;
+  paths: SensitivePathContext;
+}
+
+/** Built-in default Tool Policy for one call, or `undefined` when the tool has none. */
+function builtInDefault(call: ToolPolicyInput): ResolvedToolPolicy | undefined {
+  const { toolName, input } = call;
+  if (allowedByDefault.includes(toolName)) return { policy: "allow", source: "default" };
+  if (reviewedByDefault.includes(toolName)) return { policy: "review", source: "default" };
+  if (toolName === "edit" || toolName === "write") {
+    const path = input["path"];
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- SAFETY: tool arguments are model-supplied JSON; a non-string path cannot be judged and is reviewed.
+    if (typeof path !== "string")
+      return { policy: "review", source: "default", detail: "the target path is not a string" };
+    const reason = sensitivePathReason(path, call.paths);
+    return reason
+      ? { policy: "review", source: "default", detail: `Sensitive Path: ${reason}` }
+      : { policy: "allow", source: "default" };
+  }
+  if (toolName === "bash") {
+    const command = input["command"];
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- SAFETY: tool arguments are model-supplied JSON; a non-string command cannot be judged and is reviewed.
+    if (typeof command === "string" && isSafeCommand(command, call.safeCommands))
+      return { policy: "allow", source: "default" };
+    return { policy: "review", source: "default", detail: "not a Safe Command" };
+  }
+  return undefined;
+}
+
+/**
+ * Resolve one call's Tool Policy: the configured `tools` entry, else the built-in default
+ * (including Safe Command and Sensitive Path exemptions), else a `readOnlyHint` annotation without
+ * `openWorldHint`, else review.
+ */
+export function resolveToolPolicy(call: ToolPolicyInput): ResolvedToolPolicy {
+  const configured = Object.hasOwn(call.configured, call.toolName)
+    ? call.configured[call.toolName]
+    : undefined;
+  if (configured) return { policy: configured, source: "setting" };
+  const fallback = builtInDefault(call);
+  if (fallback) return fallback;
+  // A read-only tool that reaches the open world, such as a URL fetch, can still send data out.
+  if (call.annotations?.readOnlyHint === true && call.annotations.openWorldHint !== true)
+    return { policy: "allow", source: "annotation" };
+  return { policy: "review", source: "fallback" };
+}