@herbertgao/pi-extensions 2026.9.8 → 2026.9.9

package/node_modules/pi-jev-auto-mode/src/policy.ts

@@ -0,0 +1,558 @@
+/**
+ * Deterministic policy layer.
+ *
+ * Everything in this module runs before Jev. Hard-deny rules are deliberate,
+ * non-overridable, and must never be reachable by a probabilistic decision: they
+ * are the floor that keeps a mis-calibrated semantic verdict from becoming an
+ * approved `rm -rf /`.
+ *
+ * The command pattern catalogue is adapted from the MIT-licensed
+ * `@nilskluewer/pi-auto-permission-gate` extension; see README "Acknowledgements".
+ */
+
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export interface CommandRuleConfig {
+  /** Shell-style `*` / `?` patterns that auto-approve without asking Jev. */
+  readonly allowedCommands: readonly string[];
+  /** Shell-style patterns that block immediately, before Jev. */
+  readonly disallowedCommands: readonly string[];
+}
+
+export interface UserRuleDecision {
+  readonly decision: "allow" | "deny";
+  readonly pattern: string;
+  readonly source: "user-allow" | "user-disallow";
+}
+
+export interface CommandPattern {
+  readonly name: string;
+  readonly pattern: RegExp;
+}
+
+/**
+ * Read-only inspection commands.
+ *
+ * These run without producing a decision record: they cannot change state outside
+ * the working tree, so gating them would only add latency.
+ *
+ * The built-in list is deliberately stack-neutral and contains no command that
+ * executes project code. A verification runner (`uv run pytest`, `npm run test`,
+ * `cargo test`, `go test`, ...) executes arbitrary code from the repository, which
+ * is exactly the category the gate exists to judge — so those belong in the user's
+ * `safeCommands` setting, where the choice is explicit and local.
+ */
+export const SAFE_COMMANDS: readonly string[] = [
+  // Shell state and navigation
+  "pwd",
+  "cd*",
+  "ls*",
+  "tree*",
+  "whoami",
+  "hostname",
+  "uname*",
+  "date",
+  // Reading files and stdin. Shell redirection and pipes are rejected by the matcher,
+  // and a credential path is caught by the dangerous patterns before this list, so
+  // `cat*` cannot read a secret out of the gate's sight.
+  "cat*",
+  "bat*",
+  "head*",
+  "tail*",
+  "less*",
+  "wc*",
+  "file*",
+  "stat*",
+  "realpath*",
+  "readlink*",
+  "basename*",
+  "dirname*",
+  "du*",
+  "df*",
+  // `find -delete` and `find -exec` match dangerous patterns and are judged first.
+  "find*",
+  // Searching and transforming text without writing files
+  "grep*",
+  "rg*",
+  "ag*",
+  "jq*",
+  "diff*",
+  "cmp*",
+  "sort*",
+  "uniq*",
+  "cut*",
+  "column*",
+  "nl*",
+  "xxd*",
+  // Interpreter and tool versions
+  "node --version*",
+  "npm --version*",
+  "python --version*",
+  "python3 --version*",
+  "uv --version*",
+  "go version*",
+  "cargo --version*",
+  "gh --version*",
+  // Git inspection. Destructive variants (`tag -d`, `branch -D`, `clean -f`,
+  // `push --force`) match dangerous patterns and are judged before this list.
+  "git status*",
+  "git diff*",
+  "git log*",
+  "git show*",
+  "git branch",
+  "git remote",
+  "git remote -v",
+  "git blame*",
+  "git shortlog*",
+  "git describe*",
+  "git rev-parse*",
+  "git ls-files*",
+  "git ls-tree*",
+  "git worktree list*",
+  "git stash list*",
+  "git tag",
+];
+
+/**
+ * Shell control syntax. An allow pattern that matches through `;`, `&&`, `|`,
+ * redirection, or substitution would smuggle a second command past the gate, so
+ * allow patterns are disabled for commands containing any of these.
+ */
+const SHELL_CONTROL_CHARACTERS = /[\r\n;&|<>$`()\\]/;
+const PATH_GLOB_CHARACTERS = /[*?[\]{}]/;
+
+const REGEX_SPECIAL_CHARACTERS = /[.*+?^${}()|[\]\\]/g;
+
+function commandGlobToRegExp(pattern: string): RegExp {
+  let source = "^";
+  for (const character of pattern) {
+    if (character === "*") {
+      source += "[\\s\\S]*";
+    } else if (character === "?") {
+      source += "[\\s\\S]";
+    } else {
+      source += character.replace(REGEX_SPECIAL_CHARACTERS, "\\$&");
+    }
+  }
+  return new RegExp(`${source}$`, "i");
+}
+
+export function matchesCommandPattern(command: string, pattern: string, allowShellControl: boolean): boolean {
+  const normalizedPattern = pattern.trim();
+  if (!normalizedPattern) return false;
+  if (normalizedPattern.includes("\n") || normalizedPattern.includes("\r")) return false;
+  if (!allowShellControl && SHELL_CONTROL_CHARACTERS.test(command)) return false;
+  return commandGlobToRegExp(normalizedPattern).test(command.trim());
+}
+
+function matchesAnyCommandPattern(
+  command: string,
+  patterns: readonly string[],
+  allowShellControl: boolean,
+): string | undefined {
+  return patterns.find((pattern) => matchesCommandPattern(command, pattern, allowShellControl));
+}
+
+/**
+ * User rules, in precedence order: deny beats allow. Hard-deny rules are applied
+ * separately and cannot be overridden by either list.
+ */
+export function evaluateUserCommandRules(
+  command: string,
+  config: CommandRuleConfig,
+): UserRuleDecision | undefined {
+  // Deny patterns may contain shell control syntax: the user is naming a command
+  // to refuse, so a looser match is the safer failure direction.
+  const deniedPattern = matchesAnyCommandPattern(command, config.disallowedCommands, true);
+  if (deniedPattern) return { decision: "deny", pattern: deniedPattern, source: "user-disallow" };
+
+  const allowedPattern = matchesAnyCommandPattern(command, config.allowedCommands, false);
+  if (allowedPattern) return { decision: "allow", pattern: allowedPattern, source: "user-allow" };
+  return undefined;
+}
+
+/** Commands that are considered dangerous and must therefore be judged. */
+const DANGEROUS_PATTERNS: readonly CommandPattern[] = [
+  // File deletion / destructive filesystem traversal
+  {
+    name: "recursive/forced rm",
+    pattern: /\brm\b(?=[^\n;&|]*\s-(?:[^\s;&|]*[rR][^\s;&|]*[fF]?|[^\s;&|]*[fF][^\s;&|]*[rR])\b|[^\n;&|]*\s--recursive\b)/i,
+  },
+  { name: "remove Git metadata", pattern: /\brm\b[^\n;&|]*\s(?:\.git|\.git\/|['"]\.git['"])/i },
+  { name: "find delete", pattern: /\bfind\b[^\n;&|]*\s-delete\b/i },
+  { name: "xargs rm", pattern: /\bxargs\b[^\n;&|]*\brm\b/i },
+
+  // Package execution and publishing can run third-party code or change remote state
+  {
+    name: "package execution or publish",
+    pattern:
+      /\b(?:npm|pnpm|yarn|bun|pip|pip3|uv|poetry|cargo|gem|go|brew|apt(?:-get)?|dnf|pacman)\b[^\n;&|]*\b(?:exec|run|dlx|publish)\b/i,
+  },
+  { name: "package runner", pattern: /\b(?:npx|pnpm\s+dlx|yarn\s+dlx|bunx|pipx|uvx)\b/i },
+
+  // Privilege escalation / permission or ownership foot-guns
+  { name: "sudo", pattern: /\bsudo\b/i },
+  { name: "world-writable permissions", pattern: /\bchmod\b[^\n;&|]*\b777\b/i },
+  { name: "recursive chmod/chown", pattern: /\b(?:chmod|chown)\b[^\n;&|]*\s(?:-R|--recursive)\b/i },
+
+  // Disk / partition / filesystem destruction
+  { name: "format filesystem", pattern: /\bmkfs(?:\.[a-z0-9_+-]+)?\b/i },
+  { name: "wipe filesystem signatures", pattern: /\bwipefs\b/i },
+  { name: "disk shred/wipe", pattern: /\b(?:shred|srm)\b/i },
+  { name: "partition editor", pattern: /\b(?:fdisk|parted|gparted|sfdisk|cfdisk)\b/i },
+  { name: "macOS disk erase", pattern: /\bdiskutil\b[^\n;&|]*\b(?:erase|partition|apfs\s+delete|apfs\s+erase)\b/i },
+  { name: "dd writes to disk device", pattern: /\bdd\b[^\n;&|]*\bof=\/dev\//i },
+
+  // Git working tree / repo / history destruction
+  { name: "git reset hard", pattern: /\bgit\b[^\n;&|]*\breset\b[^\n;&|]*\s--hard\b/i },
+  { name: "git clean forced", pattern: /\bgit\b[^\n;&|]*\bclean\b(?=[^\n;&|]*\s-[^\s;&|]*f)[^\n;&|]*/i },
+  { name: "git force push", pattern: /\bgit\b[^\n;&|]*\bpush\b[^\n;&|]*\s--(?:force|force-with-lease|mirror)\b/i },
+  { name: "git force push", pattern: /\bgit\b[^\n;&|]*\bpush\b[^\n;&|]*\s-[^\s;&|]*f[^\s;&|]*\b/i },
+  { name: "git branch force-delete", pattern: /\bgit\b[^\n;&|]*\bbranch\b[^\n;&|]*\s-D\b/i },
+  { name: "git tag delete", pattern: /\bgit\b[^\n;&|]*\btag\b[^\n;&|]*\s-d\b/i },
+  { name: "git remove files", pattern: /\bgit\b[^\n;&|]*\brm\b/i },
+  { name: "git checkout all files", pattern: /\bgit\b[^\n;&|]*\bcheckout\b[^\n;&|]*\s--\s+(?:\.|\*)\b/i },
+  { name: "git restore all files", pattern: /\bgit\b[^\n;&|]*\brestore\b[^\n;&|]*(?:\s\.\b|\s:\/\b|\s--source\b)/i },
+  { name: "git reflog expiry", pattern: /\bgit\b[^\n;&|]*\breflog\b[^\n;&|]*\bexpire\b/i },
+  {
+    name: "git aggressive prune/gc",
+    pattern: /\bgit\b[^\n;&|]*\b(?:gc|prune)\b[^\n;&|]*(?:--prune=(?:now|all)|--expire\s+now|--expire=now)/i,
+  },
+
+  // Containers / volumes can destroy local databases and development state
+  {
+    name: "docker prune/remove volumes",
+    pattern: /\bdocker\b[^\n;&|]*\b(?:system\s+prune|volume\s+(?:rm|prune)|container\s+prune|image\s+prune)\b/i,
+  },
+  {
+    name: "docker compose remove volumes",
+    pattern: /\bdocker\s+compose\b[^\n;&|]*\bdown\b[^\n;&|]*(?:\s-v\b|\s--volumes\b)/i,
+  },
+
+  // Running remote scripts gives the author of that script the current user's access
+  {
+    name: "downloaded script execution",
+    pattern: /\b(?:curl|wget)\b[^\n;&|]*(?:\|\s*(?:sh|bash|zsh)\b|\b(?:sh|bash|zsh)\s*<\s*\()/i,
+  },
+
+  // Sending local data out. Missing this class entirely was a real hole: a request
+  // that uploads a file matched nothing and ran with no judgment at all.
+  {
+    name: "network upload of local data",
+    pattern:
+      /\b(?:curl|wget)\b[^\n;&|]*(?:\s-d\s*@|\s--data(?:-binary|-raw|-urlencode)?\s*@|\s-T\s|\s--upload-file\b|\s-F\s[^\s;&|]*=@|\s--form\s[^\s;&|]*=@)/i,
+  },
+  { name: "file transfer to a remote host", pattern: /\b(?:scp|rsync|sftp)\b/i },
+  { name: "raw network connection", pattern: /\b(?:nc|ncat|netcat|telnet)\b/i },
+
+  // Reading credential material into the transcript. Reading has no side effect, but
+  // a private key pasted into a conversation is a leak with a long half-life.
+  {
+    name: "reads a credential file",
+    pattern:
+      /\b(?:cat|bat|less|more|head|tail|xxd|base64|grep|rg)\b[^\n;&|]*(?:\.ssh\/|id_rsa|id_ed25519|id_ecdsa|\.aws\/|\.gnupg|\.npmrc|credentials|\.env\b(?!\.(?:example|sample|template)))/i,
+  },
+];
+
+/**
+ * Catastrophic targets. These are never handed to Jev: a look-alike approval
+ * would be unsafe even when the surrounding conversation seems to ask for it.
+ *
+ * The list is deliberately small. Everything else belongs to the semantic layer,
+ * where context and user intent can legitimately change the answer.
+ */
+const HARD_DENY_PATTERNS: readonly CommandPattern[] = [
+  {
+    name: "recursive delete of a system or home root",
+    pattern:
+      /\brm\b[^\n;&|]*(?:--recursive|-[^\s;&|]*[rR][^\s;&|]*)[^\n;&|]*\s+["']?(?:\/|~|\$HOME|\$\{HOME\}|\/(?:Users|home|root|System|Applications|Library|etc|usr|var|bin|sbin|opt|private|Volumes))(?:["']?(?:\s|$)|\/)/i,
+  },
+  {
+    name: "unresolved recursive delete target",
+    pattern:
+      /\brm\b(?=[^\n;&|]*(?:--recursive|-[^\s;&|]*[rR][^\s;&|]*))(?=[^\n;&|]*(?:\$\(|\$\{|\$[A-Za-z_]|\$['"]|~[A-Za-z]|[`*?[\]{}]|\{[^}]*,))[^\n;&|]*/i,
+  },
+  { name: "filesystem format or signature wipe", pattern: /\b(?:mkfs(?:\.[a-z0-9_+-]+)?|wipefs)\b/i },
+  { name: "disk device overwrite", pattern: /\bdd\b[^\n;&|]*\bof\s*=\s*["']?\/dev\//i },
+  {
+    name: "macOS disk erase or partition",
+    pattern: /\bdiskutil\b[^\n;&|]*\b(?:erase|partition|apfs\s+delete|apfs\s+erase)\b/i,
+  },
+  {
+    name: "forced push to a protected branch",
+    pattern:
+      /\bgit\b[^\n;&|]*\bpush\b[^\n;&|]*(?:--force(?:-with-lease)?|-[^\s;&|]*f[^\s;&|]*)\b[^\n;&|]*\b(?:main|master|production|prod)\b/i,
+  },
+  {
+    name: "forced push to a protected branch",
+    pattern:
+      /\bgit\b[^\n;&|]*\bpush\b[^\n;&|]*\b(?:main|master|production|prod)\b[^\n;&|]*(?:--force(?:-with-lease)?|-[^\s;&|]*f[^\s;&|]*)\b/i,
+  },
+  {
+    name: "unresolved forced push target",
+    pattern:
+      /\bgit\b(?=[^\n;&|]*\bpush\b)(?=[^\n;&|]*(?:--force(?:-with-lease)?|-[^\s;&|]*f[^\s;&|]*))(?=[^\n;&|]*(?:\$\(|\$\{|\$[A-Za-z_]|\$['"]|~[A-Za-z]|[`*?[\]{}]|\{[^}]*,))[^\n;&|]*/i,
+  },
+];
+
+export function hardDenyReasons(command: string): string[] {
+  return unique(HARD_DENY_PATTERNS.filter(({ pattern }) => pattern.test(command)).map(({ name }) => name));
+}
+
+const LOCAL_DELETION_REASONS = new Set(["recursive/forced rm", "find delete"]);
+
+const FIND_NARROWING_PREDICATES = new Set([
+  "-atime",
+  "-ctime",
+  "-empty",
+  "-group",
+  "-iname",
+  "-ipath",
+  "-iregex",
+  "-links",
+  "-maxdepth",
+  "-mindepth",
+  "-mtime",
+  "-name",
+  "-newer",
+  "-newermt",
+  "-path",
+  "-perm",
+  "-regex",
+  "-size",
+  "-type",
+  "-user",
+]);
+
+function isSafeRelativeDeletionTarget(target: string, cwd: string, allowCurrentDirectory: boolean): boolean {
+  if (!target) return false;
+  if (target.startsWith("/") || target.startsWith("~") || target.startsWith("$")) return false;
+  if (/^[A-Za-z]:[\\/]/.test(target)) return false;
+  if (PATH_GLOB_CHARACTERS.test(target)) return false;
+
+  const normalizedSegments = target.replace(/^\.\/+/, "").split(/[\\/]/);
+  if (!allowCurrentDirectory && normalizedSegments.length === 1 && normalizedSegments[0] === "") return false;
+  if (normalizedSegments.some((segment) => segment === ".." || segment === ".git")) return false;
+
+  const projectRoot = resolve(cwd);
+  const resolvedTarget = resolve(projectRoot, target);
+  const relativeTarget = relative(projectRoot, resolvedTarget);
+  return (
+    Boolean(relativeTarget) &&
+    relativeTarget !== ".." &&
+    !relativeTarget.startsWith(`..${sep}`) &&
+    !relativeTarget.startsWith(sep)
+  );
+}
+
+function isScopedRmCommand(command: string, cwd: string): boolean {
+  if (SHELL_CONTROL_CHARACTERS.test(command) || PATH_GLOB_CHARACTERS.test(command)) return false;
+  const tokens = command.trim().split(/[ \t]+/).filter(Boolean);
+  if (tokens.shift()?.toLowerCase() !== "rm") return false;
+
+  let optionsEnded = false;
+  const targets: string[] = [];
+  for (const token of tokens) {
+    if (!optionsEnded && token === "--") {
+      optionsEnded = true;
+      continue;
+    }
+    if (!optionsEnded && token.startsWith("-")) continue;
+    // An option after the first target means the command is not a simple deletion.
+    if (token.startsWith("-")) return false;
+    targets.push(token);
+  }
+
+  return targets.length > 0 && targets.every((target) => isSafeRelativeDeletionTarget(target, cwd, false));
+}
+
+function isScopedFindDeleteCommand(command: string, cwd: string): boolean {
+  if (SHELL_CONTROL_CHARACTERS.test(command) || PATH_GLOB_CHARACTERS.test(command)) return false;
+  const tokens = command.trim().split(/[ \t]+/).filter(Boolean);
+  if (tokens.shift()?.toLowerCase() !== "find") return false;
+  if (tokens.includes("-exec") || tokens.includes("-execdir")) return false;
+  if (!tokens.includes("-delete")) return false;
+
+  const expressionStart = tokens.findIndex(
+    (token) => token.startsWith("-") || token === "!" || token === "(" || token === ")",
+  );
+  if (expressionStart <= 0) return false;
+
+  const roots = tokens.slice(0, expressionStart);
+  const hasNarrowingPredicate = tokens.some((token) => FIND_NARROWING_PREDICATES.has(token));
+  return roots.length > 0 && roots.every((root) => isSafeRelativeDeletionTarget(root, cwd, hasNarrowingPredicate));
+}
+
+/** `rm -rf build` / `find build -type f -delete` under the working directory. */
+export function isScopedLocalDeletionCommand(command: string, cwd: string): boolean {
+  return isScopedRmCommand(command, cwd) || isScopedFindDeleteCommand(command, cwd);
+}
+
+/** Read-only built-ins only: the commands the gate can vouch for on its own. */
+export function isReadOnlyCommand(command: string): boolean {
+  return matchesAnyCommandPattern(command, SAFE_COMMANDS, false) !== undefined;
+}
+
+/**
+ * A chain of read-only commands, such as `cd src && ls -la && git log`.
+ *
+ * Agents chain commands constantly, and a single `&&` would otherwise take an
+ * otherwise harmless line out of the fast path and into a judgment round trip.
+ * Every segment must be read-only on its own; `curl … | sh` splits into `curl …`
+ * (not on the list) and `sh` (not on the list), so it is still judged, and a
+ * segment containing a redirection fails the matcher anyway.
+ */
+export function isReadOnlyCommandChain(command: string): boolean {
+  const segments = command
+    .split(/&&|\|\||;|\||\n/)
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0);
+  if (segments.length === 0) return false;
+  return segments.every((segment) => isReadOnlyCommand(segment));
+}
+
+/**
+ * Patterns the user declared safe.
+ *
+ * Kept separate from the built-in list because the two have different standing: a
+ * user declaration outranks a dangerous-pattern match, while the built-in read-only
+ * list does not (`grep secret ~/.ssh/id_ed25519` looks like reading and must still be
+ * judged).
+ */
+export function isUserDeclaredSafeCommand(command: string, safeCommands: readonly string[]): boolean {
+  return matchesAnyCommandPattern(command, safeCommands, false) !== undefined;
+}
+
+/** Either list. Convenience for callers that do not need the distinction. */
+export function isSafeCommand(command: string, extraPatterns: readonly string[] = []): boolean {
+  return isReadOnlyCommand(command) || isUserDeclaredSafeCommand(command, extraPatterns);
+}
+
+/**
+ * Names of the dangerous patterns a bash command matches, i.e. the reasons this
+ * call has to be judged instead of running straight through.
+ *
+ * Returns an empty array when the command is safe to run as far as this layer can
+ * tell. That is the fast path: the default is to stay out of the way.
+ */
+export function dangerousReasons(command: string, cwd?: string): string[] {
+  const reasons = unique(DANGEROUS_PATTERNS.filter(({ pattern }) => pattern.test(command)).map(({ name }) => name));
+  if (cwd && isScopedLocalDeletionCommand(command, cwd)) {
+    return reasons.filter((reason) => !LOCAL_DELETION_REASONS.has(reason));
+  }
+  return reasons;
+}
+
+/** Directories that hold credentials, agent configuration, or CI definitions. */
+export const PROTECTED_DIRECTORY_SEGMENTS: readonly string[] = [
+  ".git",
+  ".ssh",
+  ".aws",
+  ".gnupg",
+  ".husky",
+  ".pi",
+  ".claude",
+  ".codex",
+];
+
+/** Path fragments that are security-relevant even outside the segments above. */
+const PROTECTED_PATH_FRAGMENTS: readonly string[] = ["/.github/workflows/", "/.config/gh/"];
+
+const PROTECTED_FILE_PATTERNS: readonly RegExp[] = [
+  // `.env.example` and friends are templates that belong in the repository, so they are
+  // not treated as credential stores. The real files still are.
+  /^\.env(?!\.(?:example|sample|template|dist)$)(?:\..+)?$/i,
+  /^\.npmrc$/i,
+  /^\.netrc$/i,
+  /^\.mcp\.json$/i,
+  /^credentials(?:\.json)?$/i,
+  /^id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?$/i,
+  /\.(?:pem|key|p12|pfx)$/i,
+  /^\.(?:zshrc|bashrc|bash_profile|profile|zprofile|zlogin)$/i,
+  // Agent instruction files are a prompt-injection surface: a write there can
+  // change what the agent believes it has been told.
+  /^AGENTS\.md$/i,
+  /^CLAUDE\.md$/i,
+];
+
+function normalizeForMatching(absolutePath: string): string {
+  return absolutePath.replace(/\\/g, "/");
+}
+
+/**
+ * Classify a path against the protected locations.
+ *
+ * `extraProtectedPaths` comes from settings. An entry containing `/` is matched as a
+ * path fragment; anything else is matched against the file name. Matching is
+ * case-insensitive on the normalized path.
+ */
+export function protectedPathReason(
+  absolutePath: string,
+  extraProtectedPaths: readonly string[] = [],
+): string | undefined {
+  // Matching is case-insensitive, but the reported name keeps the original case:
+  // the message is read by a person looking at their own path.
+  const normalized = normalizeForMatching(absolutePath);
+  const lowered = normalized.toLowerCase();
+  const segments = normalized.split("/").filter(Boolean);
+  const loweredSegments = lowered.split("/").filter(Boolean);
+  const baseName = segments[segments.length - 1] ?? "";
+  const loweredBaseName = loweredSegments[loweredSegments.length - 1] ?? "";
+
+  const extraEntry = extraProtectedPaths
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .find((entry) => {
+      const loweredEntry = entry.toLowerCase();
+      return loweredEntry.includes("/") ? lowered.includes(loweredEntry) : loweredBaseName === loweredEntry;
+    });
+  if (extraEntry) return `configured protected path \`${extraEntry}\``;
+
+  const segment = loweredSegments.find((part) => PROTECTED_DIRECTORY_SEGMENTS.includes(part));
+  if (segment) return `protected directory \`${segment}\``;
+
+  const fragment = PROTECTED_PATH_FRAGMENTS.find((part) => lowered.includes(part));
+  if (fragment) return `protected path \`${fragment}\``;
+
+  const filePattern = PROTECTED_FILE_PATTERNS.find((pattern) => pattern.test(baseName));
+  if (filePattern) return `protected file \`${baseName}\``;
+
+  return undefined;
+}
+
+export interface WriteTarget {
+  readonly absolute: string;
+  readonly relativeToCwd: string | undefined;
+  readonly outsideCwd: boolean;
+  readonly protectedReason: string | undefined;
+}
+
+/**
+ * Classify a write/edit target lexically.
+ *
+ * A symlink inside the working directory can still point outside it; resolving
+ * that needs a filesystem call and belongs to the Jev layer's state building.
+ */
+export function classifyWriteTarget(
+  inputPath: string,
+  cwd: string,
+  extraProtectedPaths: readonly string[] = [],
+): WriteTarget {
+  const projectRoot = resolve(cwd);
+  const absolute = resolve(projectRoot, inputPath);
+  const relativeToCwd = relative(projectRoot, absolute);
+  const outsideCwd = isAbsolute(relativeToCwd)
+    ? true
+    : relativeToCwd === ".." || relativeToCwd.startsWith(`..${sep}`) || relativeToCwd === "";
+
+  return {
+    absolute,
+    relativeToCwd: outsideCwd ? undefined : relativeToCwd,
+    outsideCwd,
+    protectedReason: protectedPathReason(absolute, extraProtectedPaths),
+  };
+}
+
+export function unique<T>(values: readonly T[]): T[] {
+  return [...new Set(values)];
+}

package/node_modules/pi-jev-auto-mode/src/records.ts

@@ -0,0 +1,118 @@
+/**
+ * Decision records.
+ *
+ * Records are written with `pi.appendEntry`, which keeps them out of the LLM
+ * context on purpose: the model must not learn to argue with the gate, and a
+ * recorded rationale should not become ammunition for the next tool call.
+ */
+
+import { Box, Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ConditionReport, DecisionSource } from "./decide.ts";
+import { formatThreshold } from "./jev/decide.ts";
+
+export const DECISION_ENTRY_TYPE = "jev-auto-mode-decision";
+
+export interface DecisionRecord {
+  readonly tool: string;
+  readonly summary: string;
+  readonly reasons: readonly string[];
+  readonly status: "allowed" | "blocked" | "confirmed" | "cancelled";
+  readonly source: DecisionSource;
+  readonly rationale: string;
+  /** One entry per condition that was asked, in the order they were asked. */
+  readonly conditions?: readonly ConditionReport[];
+  readonly decidingRule?: string;
+  readonly clearedByIntent?: readonly string[];
+  readonly probabilities?: Readonly<Record<string, number>>;
+  readonly model?: string;
+  readonly latencyMs?: number;
+  readonly timestamp: number;
+}
+
+export type DecisionRecorder = (record: DecisionRecord) => void;
+
+export function createRecorder(pi: Pick<ExtensionAPI, "appendEntry">): DecisionRecorder {
+  return (record) => {
+    try {
+      pi.appendEntry(DECISION_ENTRY_TYPE, record);
+    } catch (error) {
+      console.warn("[jev-auto-mode] could not record a decision:", error);
+    }
+  };
+}
+
+const STATUS_LABEL: Record<DecisionRecord["status"], string> = {
+  allowed: "allowed",
+  blocked: "blocked",
+  confirmed: "confirmed by user",
+  cancelled: "cancelled by user",
+};
+
+export function formatDecisionLine(record: DecisionRecord): string {
+  const parts = [`${record.tool}: ${STATUS_LABEL[record.status]}`, `via ${record.source}`];
+  if (record.decidingRule) parts.push(`decided by ${record.decidingRule}`);
+  if (record.model) parts.push(record.model);
+  if (typeof record.latencyMs === "number") parts.push(`${Math.round(record.latencyMs)}ms`);
+  return parts.join(" · ");
+}
+
+const VERDICT_MARK: Record<ConditionReport["verdict"], string> = {
+  satisfied: "pass",
+  rejected: "reject",
+  uncertain: "unclear",
+  ignored: "ignored",
+};
+
+/**
+ * One line per condition, with the band it landed in and the threshold it was
+ * compared against. This is the view used to decide whether a threshold needs to
+ * move, so it shows the passing values too.
+ */
+export function formatConditionLines(record: DecisionRecord): string[] {
+  return (record.conditions ?? []).map((condition) => {
+    const bounds =
+      condition.verdict === "satisfied"
+        ? `>= ${formatThreshold(condition.threshold)}`
+        : condition.verdict === "rejected"
+          ? `<= ${formatThreshold(1 - condition.threshold)}`
+          : `${formatThreshold(1 - condition.threshold)}-${formatThreshold(condition.threshold)}`;
+    const marks = [
+      record.decidingRule === condition.ruleId ? "<- decided" : "",
+      condition.clearedByIntent ? "(cleared by the user's request)" : "",
+    ].filter(Boolean);
+    return `${condition.ruleId}  p=${condition.probability.toFixed(2)}  ${VERDICT_MARK[condition.verdict]} (t=${formatThreshold(condition.threshold)}, ${bounds}) ${marks.join(" ")}`.trimEnd();
+  });
+}
+
+export function registerDecisionEntryRenderer(pi: Pick<ExtensionAPI, "registerEntryRenderer">): void {
+  pi.registerEntryRenderer<DecisionRecord>(DECISION_ENTRY_TYPE, (entry, options, theme) => {
+    const record = entry.data;
+    if (!record) return undefined;
+
+    const approved = record.status === "allowed" || record.status === "confirmed";
+    const icon = approved ? "🛡" : "⛔";
+    const heading = `${icon} ${theme.bold("jev auto mode")} ${theme.fg(
+      approved ? "success" : "error",
+      STATUS_LABEL[record.status],
+    )}`;
+
+    const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+    box.addChild(new Text(heading));
+    box.addChild(new Text(theme.fg("muted", formatDecisionLine(record))));
+    box.addChild(new Text(record.summary));
+    if (record.reasons.length > 0) {
+      box.addChild(new Text(theme.fg("dim", `reasons: ${record.reasons.join(", ")}`)));
+    }
+    box.addChild(new Text(theme.fg("dim", `rationale: ${record.rationale}`)));
+
+    if (options.expanded) {
+      for (const line of formatConditionLines(record)) {
+        box.addChild(new Text(theme.fg("dim", line)));
+      }
+      box.addChild(new Text(theme.fg("dim", JSON.stringify(record, null, 2))));
+    }
+
+    return box;
+  });
+}