@fusengine/harness 0.1.90 → 0.1.92

package/src/policy/guards/bash-write-patterns.ts

@@ -0,0 +1,140 @@
+import { CMD } from "./bash-command-anchor";
+
+/** Code-file extensions the write guards police (shared by CODE_REDIRECT and
+ *  CODE_COMMAND_WRITE). Case-sensitive, parity with the Python guard's list. */
+const CODE_EXT = "ts|tsx|js|jsx|py|go|rb|rs|java|kt|php|swift|vue|svelte|astro|css|c|cpp|h";
+
+/** Redirect (`>`/`>>`) targeting a code-file extension. */
+export const CODE_REDIRECT: RegExp = new RegExp(`(?:>>?)\\s*[^\\s|;&]*\\.(?:${CODE_EXT})\\b`);
+
+/**
+ * Interpreters / tools that mutate source in place, plus heredoc-into-file —
+ * split into labeled sub-patterns (parity bash-write-guard.py `DENY_PATTERNS`,
+ * each with its own `desc`) so the deny reason names which motif matched
+ * instead of a single generic message. Every command-named motif is
+ * {@link CMD}-anchored (start/separator + optional wrapper chain); only the
+ * structural heredoc-into-file motif is position-free.
+ */
+export const CODE_MUTATORS: readonly { re: RegExp; desc: string }[] = [
+  { re: new RegExp(`${CMD}python3?\\s+-\\s*<<`), desc: "Python heredoc input" },
+  { re: new RegExp(`${CMD}sed\\b[^|]*\\s-i`), desc: "sed in-place edit" },
+  { re: new RegExp(`${CMD}perl\\b[^|]*\\s-[pi]i?\\b`), desc: "perl in-place edit" },
+  { re: new RegExp(`${CMD}awk\\b[^|]*-i\\s*inplace`), desc: "awk in-place edit" },
+  // `patch` as a command token (start/separator + optional wrapper chain), then a
+  // metachar/space/EOL. Never the bare word merely NAMING a path in a read-only
+  // command (`jq . apply-patch.json`, `grep patch src/`). Prefix-wrapped forms
+  // (`env patch`, `timeout 5 patch`) are now DENIED — the previously accepted gap
+  // was closed (owner decision 2026-07-06): the wrapper chain folds into CMD.
+  { re: new RegExp(`${CMD}patch(?=\\s|<|[;&|)>]|$)`), desc: "patch file modification" },
+  { re: /<<[-~]?\s*['"]?\w+['"]?[\s\S]*?>/, desc: "heredoc redirected into a file" },
+];
+
+/**
+ * `tee`/`dd of=` whose TARGET is a code file — the command-form parallel to
+ * CODE_REDIRECT. {@link CMD}-anchored so `env`/`timeout` wrappers don't shield
+ * it; the `tee` branch scans ALL args up to the next `;&|` separator so a
+ * decoy-first-target (`tee log.txt src/x.ts`) can't hide the code write. A tee
+ * to a NON-code target (`cmd | tee results.txt`) does not match — it stays a
+ * plain ASK_WRITERS ask, never a hard block, so ordinary logging is untouched.
+ */
+export const CODE_COMMAND_WRITE: RegExp = new RegExp(
+  `${CMD}(?:tee\\s+[^;&|\\n]*?|dd\\b[^|]*\\bof=\\S*)\\.(?:${CODE_EXT})\\b`,
+);
+
+/** File-mutating one-liners via `node -e` / `ruby -e` (parity NODE_WRITES/RUBY_WRITES). */
+export const NODE_WRITES: RegExp =
+  /writeFile|appendFile|createWriteStream|fs\.(?:write|rename|unlink|mkdir|rmdir|copyFile)|execSync|spawnSync|child_process/;
+export const RUBY_WRITES: RegExp =
+  /File\.(?:write|open|delete|rename)|IO\.write|FileUtils|\bsystem\b|\bexec\b|`[^`]/;
+
+/**
+ * Command-position anchor for `python3 -c` (same anchored-token shape as the
+ * removed unconditional CODE_MUTATORS entry) — used ONLY to gate {@link PYTHON_WRITES}
+ * below, never as a standalone block. `python3 - <<EOF` (heredoc) stays
+ * unconditionally blocked in CODE_MUTATORS — a heredoc body can't be inspected
+ * reliably with a single-line regex, so it is never widened.
+ */
+export const PYTHON_C_ANCHOR: RegExp = new RegExp(`${CMD}python3?\\s+-c\\b`);
+
+/**
+ * File/process-mutating constructs inside a `python3 -c` inline script (parity
+ * NODE_WRITES/RUBY_WRITES: content-gated, not name-gated). `python3 -c` is
+ * blocked ONLY when this matches — a read-only one-liner (`print(...)`,
+ * `json.load`/`json.dumps`) passes. Doc-verified against docs.python.org
+ * (functions/pathlib/shutil/subprocess/os/pickle) before writing this pattern.
+ *
+ * Families, each independently sufficient to mutate state or run arbitrary code:
+ *  - `open(...)` / `Path(...).open(...)` in a write/append/exclusive/read-write
+ *    mode — positional (`'w'`,`'x'`,`'a'`,`'r+'`,`'w+'`, …) or `mode=` kwarg, any
+ *    `b`/`t` suffix. Plain `open(f)` / `open(f, 'r')` (read-only, the default)
+ *    does NOT match.
+ *  - `pathlib.Path` mutators: `write_text`, `write_bytes`, `unlink`, `rename`,
+ *    `replace`, `mkdir`, `rmdir`, `touch`, `chmod`, `symlink_to`, `hardlink_to`,
+ *    plus 3.14+ `move`, `move_into`, `copy`, `copy_into`.
+ *  - `shutil.*` EXCLUDING the confirmed read-only members `which`,
+ *    `disk_usage`, `get_terminal_size`, `get_archive_formats`,
+ *    `get_unpack_formats` — every other shutil function copies/moves/deletes.
+ *  - `os.*` mutators/exec: `remove`, `unlink`, `rename`, `replace`, `makedirs`,
+ *    `mkdir`, `rmdir`, `removedirs`, `chmod`, `chown`, `symlink`, `link`,
+ *    `truncate`, `chdir`, `fchdir`, `putenv`, `write`, `ftruncate`, `fchmod`,
+ *    `fchown`, `fork`, `system`, `popen`, plus the `exec*`/`spawn*`/
+ *    `posix_spawn` families.
+ *  - `subprocess.run|call|check_call|check_output|Popen|getoutput|getstatusoutput`
+ *    — the actual spawn surface. Non-spawning members (`PIPE`, `DEVNULL`,
+ *    `STDOUT`, `CompletedProcess`, `CalledProcessError`, …) are deliberately
+ *    excluded — a bare `subprocess\.\w+` would false-positive on those.
+ *  - `pickle.dump` / `json.dump` (the file-writing form — `\b` after `dump`
+ *    excludes `dumps`, which only serializes to a string/bytes in memory).
+ *  - `csv.writer`, `tempfile.*` (temp-file/dir creation is still a write).
+ *  - generic `.write(`/`.writelines(` — covers any file-like object, including
+ *    one opened via a variable this static check can't trace back to `open()`.
+ *  - `exec(`/`eval(` — arbitrary code execution, not merely file I/O.
+ *
+ * Deliberately NOT included: bare `import` statements, arithmetic/string
+ * formatting, `print`, `json.load`/`json.loads`, `sys.argv`/`os.environ` reads,
+ * `os.getcwd`/`os.listdir`/`os.path.*` — none of these mutate disk or spawn.
+ */
+export const PYTHON_WRITES: RegExp = new RegExp(
+  "\\bopen\\s*\\([^)]*(?:(['\"])(?:[wax]|r\\+|\\+r)[bt]?\\1|mode\\s*=\\s*(['\"])(?:[wax]|r\\+|\\+r)[bt]?\\2)"
+    + "|\\.(?:write_text|write_bytes|unlink|rename|replace|mkdir|rmdir|touch|chmod|symlink_to|hardlink_to"
+    + "|move_into|copy_into|move|copy|write|writelines)\\s*\\("
+    + "|\\bshutil\\.(?!which\\b|disk_usage\\b|get_terminal_size\\b|get_archive_formats\\b|get_unpack_formats\\b)\\w+"
+    + "|\\bos\\.(?:remove|unlink|rename|replace|makedirs|mkdir|rmdir|removedirs|system|popen|chmod|chown|symlink"
+    + "|link|truncate|chdir|fchdir|putenv|write|ftruncate|fchmod|fchown|fork)\\b"
+    + "|\\bos\\.(?:exec|spawn|posix_spawn)\\w*\\b"
+    + "|\\bsubprocess\\.(?:run|call|check_call|check_output|Popen|getoutput|getstatusoutput)\\b"
+    + "|\\bpickle\\.dump\\b"
+    + "|\\bjson\\.dump\\b"
+    + "|\\bcsv\\.writer\\b"
+    + "|\\btempfile\\.\\w+"
+    + "|\\b(?:exec|eval)\\s*\\(",
+);
+
+/** Redirect to a non-code file. Excludes `/dev/null`, `2>`/`N>` and `>&N` fd
+ * redirects via the `(?<![0-9&])` lookbehind + `(?!…|&)` (parity has_file_redirect). */
+export const FILE_REDIRECT: RegExp =
+  /(?<![0-9&])\s*>>?\s*(?!\/dev\/null|&)[a-zA-Z./~$]/;
+
+/** Other ambiguous file writers (ASK): `tee <file>` (not `tee -a`/path) and `dd … of=` —
+ * labeled sub-patterns (parity bash-write-guard.py `ASK_PATTERNS`). */
+export const ASK_WRITERS: readonly { re: RegExp; desc: string }[] = [
+  { re: /\btee\s+[^-/\s]/, desc: "tee to file" },
+  { re: /\bdd\b[^|]*\bof=/, desc: "dd output to file" },
+];
+
+/** Commands whose first token never writes, skipped when a real redirect is
+ * present (parity bash-write-guard.py `SAFE_PREFIXES`). */
+export const SAFE_PREFIXES: readonly string[] = [
+  "ls", "pwd", "which", "cat ", "head ", "tail ", "wc ", "file ", "stat ", "tree", "du ", "df ",
+  "find ", "grep ", "rg ", "git ", "cd ", "source ", "export ", "unset ", "env ", "printenv",
+  "bun test", "bun run", "bunx ", "npm test", "npm run", "npx ", "biome ", "eslint ",
+  "prettier ", "ruff ", "pyright ", "tsc ", "mkdir ", "mv ", "cp ",
+];
+
+/**
+ * Session-state directory the freshness/APEX gates rely on. Any Bash command
+ * touching it is a hook-bypass vector, so it is blocked outright — a blunt
+ * substring match (read OR write), parity with bash-write-guard.py DENY_PATTERNS
+ * `fusengine-cache/sessions` (rebranded to the harness cache path).
+ */
+export const SESSION_STATE_FRAGMENT = ".fuse-harness/cache/sessions";

package/src/policy/guards/bash-write-redirects.ts

@@ -0,0 +1,201 @@
+/** One active shell output-redirection operator and its parsed target. */
+export type ShellRedirect = Readonly<{ start: number; operator: string; target: string }>;
+
+function closingParen(input: string, start: number): number {
+  let depth = 1;
+  let quote: "'" | '"' | null = null;
+  for (let i = start; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === "\\" && quote !== "'") { i++; continue; }
+    if (quote) { if (ch === quote) quote = null; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === "(") { depth++; continue; }
+    if (ch === ")" && --depth === 0) return i;
+  }
+  return input.length;
+}
+
+function closingBacktick(input: string, start: number): number {
+  for (let i = start; i < input.length; i++) {
+    if (input[i] === "\\") { i++; continue; }
+    if (input[i] === "`") return i;
+  }
+  return input.length;
+}
+
+function closingArithmetic(input: string, start: number): number {
+  let depth = 1;
+  let quote: "'" | '"' | null = null;
+  for (let i = start; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === "\\" && quote !== "'") { i++; continue; }
+    if (quote) { if (ch === quote) quote = null; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === "(") { depth++; continue; }
+    if (ch !== ")") continue;
+    if (depth === 1 && input[i + 1] === ")") return i + 1;
+    depth--;
+  }
+  return input.length;
+}
+
+function closingConditional(input: string, start: number): number {
+  let quote: "'" | '"' | null = null;
+  for (let i = start; i < input.length - 1; i++) {
+    const ch = input[i];
+    if (ch === "\\" && quote !== "'") { i++; continue; }
+    if (quote) { if (ch === quote) quote = null; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === "]" && input[i + 1] === "]") return i;
+  }
+  return input.length;
+}
+
+function commentStart(input: string, index: number, start: number): boolean {
+  return input[index] === "#" && (index === start || /[\s;|&()]/.test(input[index - 1] ?? ""));
+}
+
+function commandPosition(input: string, index: number, start: number): boolean {
+  const prefix = input.slice(start, index);
+  const segment = prefix.slice(Math.max(prefix.lastIndexOf(";"), prefix.lastIndexOf("|"), prefix.lastIndexOf("&"), prefix.lastIndexOf("\n")) + 1).trim();
+  return segment === "" || /^(?:if|elif|while|until|then|do|!)$/.test(segment);
+}
+
+function readTarget(input: string, start: number, end: number): string {
+  let out = "";
+  let quote: "'" | '"' | null = null;
+  for (let i = start; i < end; i++) {
+    const ch = input[i] ?? "";
+    if (ch === "\\" && quote !== "'") {
+      if (i + 1 < end) out += input[++i] ?? "";
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+      else out += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (/\s|[;&|<>]/.test(ch)) break;
+    out += ch;
+  }
+  return out;
+}
+
+function scanDoubleQuote(input: string, start: number, end: number, out: ShellRedirect[]): number {
+  for (let i = start; i < end; i++) {
+    if (input[i] === "\\") { i++; continue; }
+    if (input[i] === '"') return i;
+    if (input[i] === "$" && input[i + 1] === "(" && input[i + 2] === "(") {
+      const close = closingArithmetic(input, i + 3);
+      scanExpansions(input, i + 3, close - 1, out);
+      i = close;
+    } else if (input[i] === "$" && input[i + 1] === "(") {
+      const close = closingParen(input, i + 2);
+      scanRange(input, i + 2, close, out);
+      i = close;
+    } else if (input[i] === "`") {
+      const close = closingBacktick(input, i + 1);
+      scanRange(input, i + 1, close, out);
+      i = close;
+    }
+  }
+  return end;
+}
+
+function scanExpansions(input: string, start: number, end: number, out: ShellRedirect[]): void {
+  for (let i = start; i < end; i++) {
+    if (input[i] === "\\") { i++; continue; }
+    if (commentStart(input, i, start)) {
+      const newline = input.indexOf("\n", i + 1);
+      i = newline < 0 || newline >= end ? end : newline;
+      continue;
+    }
+    if (input[i] === "'") {
+      const close = input.indexOf("'", i + 1);
+      i = close < 0 || close >= end ? end : close;
+      continue;
+    }
+    if (input[i] === '"') { i = scanDoubleQuote(input, i + 1, end, out); continue; }
+    if (input[i] === "$" && input[i + 1] === "(" && input[i + 2] === "(") {
+      const close = closingArithmetic(input, i + 3);
+      scanExpansions(input, i + 3, close - 1, out);
+      i = close;
+    } else if (input[i] === "$" && input[i + 1] === "(") {
+      const close = closingParen(input, i + 2);
+      scanRange(input, i + 2, close, out);
+      i = close;
+    } else if (input[i] === "`") {
+      const close = closingBacktick(input, i + 1);
+      scanRange(input, i + 1, close, out);
+      i = close;
+    }
+  }
+}
+
+function scanRange(input: string, start: number, end: number, out: ShellRedirect[]): void {
+  for (let i = start; i < end; i++) {
+    const ch = input[i];
+    if (ch === "\\") { i++; continue; }
+    if (commentStart(input, i, start)) {
+      const newline = input.indexOf("\n", i + 1);
+      i = newline < 0 || newline >= end ? end : newline;
+      continue;
+    }
+    if (ch === "'") {
+      const close = input.indexOf("'", i + 1);
+      i = close < 0 || close >= end ? end : close;
+      continue;
+    }
+    if (ch === '"') { i = scanDoubleQuote(input, i + 1, end, out); continue; }
+    if (ch === "[" && input[i + 1] === "[" && commandPosition(input, i, start)) {
+      const close = closingConditional(input, i + 2);
+      scanExpansions(input, i + 2, close, out);
+      i = close + 1;
+      continue;
+    }
+    if (ch === "(" && input[i + 1] === "(" && commandPosition(input, i, start)) {
+      const close = closingArithmetic(input, i + 2);
+      scanExpansions(input, i + 2, close - 1, out);
+      i = close;
+      continue;
+    }
+    if (ch === "$" && input[i + 1] === "(" && input[i + 2] === "(") {
+      const close = closingArithmetic(input, i + 3);
+      scanExpansions(input, i + 3, close - 1, out);
+      i = close;
+      continue;
+    }
+    if (ch === "$" && input[i + 1] === "(") {
+      const close = closingParen(input, i + 2);
+      scanRange(input, i + 2, close, out);
+      i = close;
+      continue;
+    }
+    if (ch === "`") {
+      const close = closingBacktick(input, i + 1);
+      scanRange(input, i + 1, close, out);
+      i = close;
+      continue;
+    }
+    if (ch !== ">") continue;
+    if (input[i + 1] === "(") continue;
+    if (input[i - 1] === "&") { if (input[i + 1] === ">") i++; continue; }
+    let opStart = i;
+    while (opStart > start && /\d/.test(input[opStart - 1] ?? "")) opStart--;
+    if (input[opStart - 1] === "&") opStart--;
+    let cursor = i + (input[i + 1] === ">" || input[i + 1] === "|" ? 2 : 1);
+    const operator = input.slice(opStart, cursor);
+    while (/\s/.test(input[cursor] ?? "")) cursor++;
+    if (input[cursor] === "&") continue;
+    const target = readTarget(input, cursor, end);
+    if (target) out.push({ start: opStart, operator, target });
+  }
+}
+
+/** Return active output redirects, excluding quoted/escaped `>` characters. */
+export function shellOutputRedirects(command: string): ShellRedirect[] {
+  const out: ShellRedirect[] = [];
+  scanRange(command, 0, command.length, out);
+  return out;
+}

package/src/policy/guards/bash-write-safe-paths.ts

@@ -0,0 +1,62 @@
+import { join, normalize } from "node:path";
+import { homedir } from "node:os";
+import { claudeHome, fusengineCache } from "../../runtime/home-state";
+import { shellOutputRedirects } from "./bash-write-redirects";
+
+/**
+ * Writable paths the harness owns — writes here never need Write/Edit's APEX
+ * gates. Parity safe_paths.py `SAFE_WRITE_PATHS`; `~/.claude/fusengine-cache`
+ * is rebranded to `~/.fuse-harness/cache`, `~/.claude/logs` is unchanged.
+ */
+export const SAFE_WRITE_PATHS: readonly string[] = [fusengineCache(), join(claudeHome(), "logs")];
+
+/** Raw, un-expanded forms of {@link SAFE_WRITE_PATHS} for substring matching
+ * when a shell didn't expand `~` (parity safe_paths.py `_SAFE_RAW`). */
+const SAFE_WRITE_RAW: readonly string[] = ["~/.fuse-harness/cache", "~/.claude/logs"];
+
+/** Strip quotes, expand `~`/`$HOME`, normalize (parity safe_paths.resolve_path). */
+function resolvePath(raw: string): string {
+  const stripped = raw.trim().replace(/^['"]|['"]$/g, "");
+  // POSIX tilde-prefix: only `~` alone or a `~/` prefix is `$HOME`-relative.
+  // `~user`, `~2xyz`, `~+`, `~N` are login-name/dir-stack forms — leave unexpanded.
+  const expanded = stripped === "~" || stripped.startsWith("~/") ? homedir() + stripped.slice(1) : stripped;
+  return normalize(expanded.replace(/\$HOME/g, homedir()));
+}
+
+/** True when a `>`/`>>` redirect targets a harness-owned safe path (parity is_safe_write_path). */
+export function isSafeWritePath(cmd: string): boolean {
+  const targets = shellOutputRedirects(cmd)
+    .map((redirect) => resolvePath(redirect.target))
+    .filter((target) => target !== "/dev/null");
+  return targets.length > 0 && targets.every((target) => SAFE_WRITE_PATHS.some((safe) => target === safe || target.startsWith(safe + "/")));
+}
+
+/** Extract the file argument of `tee`/`dd of=` (parity extract_command_target). */
+function extractCommandTarget(cmd: string): string | null {
+  const tee = cmd.match(/\btee\s+(?:-[a-z]\s+)*(\S+)/);
+  if (tee?.[1]) return resolvePath(tee[1]);
+  const dd = cmd.match(/\bdd\b[^|]*\bof=(\S+)/);
+  return dd?.[1] ? resolvePath(dd[1]) : null;
+}
+
+/** True when a `tee`/`dd` target is a harness-owned safe path (parity is_safe_command_target). */
+export function isSafeCommandTarget(cmd: string): boolean {
+  const target = extractCommandTarget(cmd);
+  return target !== null && SAFE_WRITE_PATHS.some((safe) => target === safe || target.startsWith(safe + "/"));
+}
+
+/**
+ * True when the command quotes a safe path as a string literal (parity
+ * has_safe_write_target, hardened: the Python original — and this function
+ * before this fix — does an unanchored substring match, which fail-opens any
+ * `node -e` containing the safe path text anywhere, including inside an inert
+ * comment. Requiring it to appear as a quoted literal still covers the real
+ * use case (`fs.appendFileSync('~/.fuse-harness/cache/x.json', ...)`).
+ */
+export function hasSafeWriteTarget(cmd: string): boolean {
+  // Quote-anchored segment boundary: exact quoted literal OR quoted sub-path
+  // (e.g. 'fusengineCache()/x.json' — a real file under the safe dir).
+  const quoted = (p: string): boolean =>
+    cmd.includes(`'${p}'`) || cmd.includes(`"${p}"`) || cmd.includes(`'${p}/`) || cmd.includes(`"${p}/`);
+  return SAFE_WRITE_PATHS.some(quoted) || SAFE_WRITE_RAW.some(quoted);
+}

package/src/policy/guards/bash-write.ts

@@ -0,0 +1,76 @@
+import type { Prompt } from "../../prompt/types";
+import type { GuardContext } from "./context";
+import { hasSafeWriteTarget, isSafeCommandTarget, isSafeWritePath } from "./bash-write-safe-paths";
+import { shellOutputRedirects } from "./bash-write-redirects";
+import {
+  ASK_WRITERS, CODE_COMMAND_WRITE, CODE_MUTATORS, NODE_WRITES,
+  PYTHON_C_ANCHOR, PYTHON_WRITES, RUBY_WRITES, SAFE_PREFIXES, SESSION_STATE_FRAGMENT,
+} from "./bash-write-patterns";
+
+export { ASK_WRITERS, CODE_MUTATORS, CODE_REDIRECT, FILE_REDIRECT, SAFE_PREFIXES, SESSION_STATE_FRAGMENT } from "./bash-write-patterns";
+
+function blockCodeWrite(reason: string): Prompt {
+  return { kind: "block", title: "Bash write to code file", reason, actions: ["Use the Write/Edit tool instead"] };
+}
+function askFileWrite(reason: string, ruleId = "bash-write:file-write"): Prompt {
+  return { kind: "ask", ruleId, title: "Bash file write", reason, actions: ["Use the Write/Edit tool instead"] };
+}
+
+/**
+ * Blocks shell commands that mutate code files in place (and heredocs/redirects
+ * to source files); asks before other file-writing shell commands unless the
+ * target is a harness-owned safe path. Forces use of the Write/Edit tool so
+ * APEX/SOLID checks are not bypassed.
+ *
+ * The code-write detectors (CODE_MUTATORS, CODE_COMMAND_WRITE) run BEFORE the
+ * SAFE_PREFIXES short-circuit: they are command-position anchored
+ * (bash-command-anchor.ts), so a transparent wrapper (`env sed -i src/x.ts`,
+ * `timeout 5 patch`, `cp a b; tee src/y.ts`) can no longer smuggle a code write
+ * past its safe first token, while a quoted mention (`git commit -m "fix sed -i"`)
+ * still falls through. The short-circuit becomes the terminal allow — "first
+ * token never writes, nothing above matched".
+ */
+export function bashWriteGuard(ctx: GuardContext): Prompt | null {
+  if (ctx.tool !== "Bash" || !ctx.command) return null;
+  const cmd: string = ctx.command;
+  const stripped = cmd.trim();
+  const redirects = shellOutputRedirects(cmd).filter((redirect) => redirect.target !== "/dev/null");
+
+  const mutator = CODE_MUTATORS.find((m) => m.re.test(cmd));
+  if (mutator) return blockCodeWrite(`${mutator.desc} — Use Edit/Write tools instead`);
+  if (CODE_COMMAND_WRITE.test(cmd)) return blockCodeWrite("tee/dd into a code file — Use Edit/Write tools instead");
+  if (PYTHON_C_ANCHOR.test(cmd) && PYTHON_WRITES.test(cmd)) {
+    return blockCodeWrite("Python inline script mutates files/spawns a process — Use Edit/Write tools instead");
+  }
+
+  if (SAFE_PREFIXES.some((p) => stripped.startsWith(p)) && redirects.length === 0) {
+    return null;
+  }
+
+  if (cmd.includes(SESSION_STATE_FRAGMENT)) {
+    return {
+      kind: "block",
+      title: "Session-state tampering",
+      reason: "Bash access to the harness session-state directory is a hook-bypass vector — the freshness/APEX enforcement reads it to decide block/allow.",
+      actions: ["Never read or write session state from the shell"],
+    };
+  }
+
+  if (redirects.length > 0) {
+    if (isSafeWritePath(cmd)) return null;
+    return redirects.some((redirect) => /\.(?:ts|tsx|js|jsx|py|go|rb|rs|java|kt|php|swift|vue|svelte|astro|css|c|cpp|h)\b/.test(redirect.target))
+      ? blockCodeWrite("Bash redirect to code file — Use Write/Edit tools (enforces APEX + SOLID specs)")
+      : askFileWrite("Shell redirect to file detected. Authorize?", "bash-write:file-redirect");
+  }
+
+  if (/\bnode\s+-e\b/.test(cmd) && NODE_WRITES.test(cmd)) {
+    return hasSafeWriteTarget(cmd) ? null : askFileWrite("Node.js write operation detected. Authorize?");
+  }
+  if (/\bruby\s+-e\b/.test(cmd) && RUBY_WRITES.test(cmd)) return askFileWrite("Ruby write operation detected. Authorize?");
+
+  const asker = ASK_WRITERS.find((a) => a.re.test(cmd));
+  if (asker) {
+    return isSafeCommandTarget(cmd) ? null : askFileWrite(`${asker.desc} detected. Authorize?`);
+  }
+  return null;
+}

package/src/policy/guards/context.ts

@@ -0,0 +1,12 @@
+import type { Prompt } from "../../prompt/types";
+
+/** Context handed to every guard in the chain. */
+export interface GuardContext {
+  tool: string;
+  filePath?: string;
+  content?: string;
+  command?: string;
+}
+
+/** A single guard: returns a blocking/asking Prompt, or null to continue. */
+export type Guard = (ctx: GuardContext) => Prompt | null;

package/src/policy/guards/index.ts

@@ -0,0 +1,61 @@
+import type { Prompt } from "../../prompt/types";
+import type { Guard, GuardContext } from "./context";
+import { securityGuard } from "./security";
+import { protectedPathGuard } from "./protected-path";
+import { bashWriteGuard } from "./bash-write";
+import { interfaceSeparationGuard } from "./interface-separation";
+import { installGuard } from "./install";
+
+export * from "./context";
+export * from "./security";
+export * from "./protected-path";
+export * from "./bash-write";
+export * from "./interface-separation";
+export * from "./install";
+
+/** Ordered guard chain: critical/security + protected first, then writes/installs. */
+export const GUARDS: ReadonlyArray<Guard> = [
+  securityGuard,
+  protectedPathGuard,
+  bashWriteGuard,
+  interfaceSeparationGuard,
+  installGuard,
+];
+
+/** Block prompt returned when a guard or gate throws (fail-closed). */
+export const FAIL_CLOSED: Prompt = {
+  kind: "block",
+  title: "Policy error",
+  reason: "A policy check errored — blocked for safety (fail-closed).",
+  actions: ["Fix the failing guard/gate, then retry"],
+};
+
+const USER_GUARDS: Guard[] = [];
+
+/** Register a user guard — runs AFTER the privileged core chain (two-tier). */
+export function registerGuard(guard: Guard): void {
+  USER_GUARDS.push(guard);
+}
+
+/** Remove all registered user guards (mainly for tests). */
+export function clearUserGuards(): void {
+  USER_GUARDS.length = 0;
+}
+
+/**
+ * Run the guard chain — privileged core guards first, then user guards — and
+ * return the first firing Prompt, else null. Fail-closed: a guard that throws
+ * blocks (never silently passes).
+ */
+export function runGuards(ctx: GuardContext): Prompt | null {
+  for (const guard of [...GUARDS, ...USER_GUARDS]) {
+    let hit: Prompt | null;
+    try {
+      hit = guard(ctx);
+    } catch {
+      return FAIL_CLOSED;
+    }
+    if (hit) return hit;
+  }
+  return null;
+}

package/src/policy/guards/install.ts

@@ -0,0 +1,22 @@
+import type { Prompt } from "../../prompt/types";
+import type { GuardContext } from "./context";
+import { matchPatterns, PROJECT_INSTALL, SYSTEM_INSTALL, isRalphMode } from "../patterns";
+
+/**
+ * Asks for confirmation before a dependency or system package install. In Ralph
+ * mode (opt-in `RALPH_MODE`) a PROJECT install is auto-approved for autonomous
+ * runs (parity install-guard.py:52), but a SYSTEM install always asks.
+ */
+export function installGuard(ctx: GuardContext): Prompt | null {
+  if (ctx.tool !== "Bash" || !ctx.command) return null;
+  const isSystem = matchPatterns(ctx.command, SYSTEM_INSTALL);
+  const isProject = matchPatterns(ctx.command, PROJECT_INSTALL);
+  if (!isSystem && !isProject) return null;
+  if (!isSystem && isProject && isRalphMode()) return null;
+  return {
+    kind: "ask",
+    title: "Dependency install",
+    reason: `This command installs packages: ${ctx.command.trim()}`,
+    actions: ["Confirm this install is intended"],
+  };
+}

package/src/policy/guards/interface-separation-ext.ts

@@ -0,0 +1,41 @@
+/**
+ * Extended interface-syntax violations (owner E3, advisory-first): the
+ * syntaxes the guard's legacy regexes miss — Swift `public protocol`,
+ * Java/Kotlin `sealed`/`fun interface`, Go unexported top-level interface
+ * (`type foo interface {` at column 0 — indented locals stay excluded, D0.2
+ * invariant). Detection rides the conventions module on MASKED content; the
+ * caller wraps the verdict with `rolloutVerdict`, so these surface as
+ * `inform` until `FUSE_CONVENTIONS_MODE=deny`. Legacy cases never reach this
+ * file (the guard's hard-deny branches return first).
+ */
+import { declaresInterface } from "../conventions/interfaces";
+import { maskCommentsAndStrings } from "../conventions/strip";
+import { langOfPath, lexProfileOf } from "../conventions/langs";
+
+/** Legacy anchors (kept in sync with interface-separation.ts by test). */
+const SWIFT_LEGACY_RE = /^\s*protocol\s+[A-Z]/m;
+const JAVA_LEGACY_RE = /^\s*(?:public\s+|private\s+|protected\s+|internal\s+)?(?:interface|record)\s+[A-Z]/m;
+const GO_LEGACY_RE = /^\s*type\s+[A-Z]\w*\s+interface\b/m;
+
+const inAny = (path: string, ...frags: string[]): boolean => frags.some((f) => path.includes(f));
+
+/**
+ * The extended-syntax violation for a file, or null when clean/legacy.
+ * @param path - The written/edited file's path.
+ * @param content - Its raw content (masked internally).
+ * @returns Message + action for the advisory prompt.
+ */
+export function extendedInterfaceViolation(path: string, content: string): { msg: string; action: string } | null {
+  if (!declaresInterface(path, content)) return null;
+  const masked = maskCommentsAndStrings(content, lexProfileOf(langOfPath(path) ?? "ts"));
+  if (/\.swift$/.test(path) && inAny(path, "View/", "Views/", "Component/", "Components/") && !SWIFT_LEGACY_RE.test(masked)) {
+    return { msg: "Protocol in view file. Move to Sources/Interfaces/", action: "Move the protocol to Sources/Interfaces/" };
+  }
+  if (/\.(java|kt)$/.test(path) && inAny(path, "controller/", "controllers/", "handler/", "handlers/") && !JAVA_LEGACY_RE.test(masked)) {
+    return { msg: "Interface in controller file. Move to interfaces/ package", action: "Move the interface to the interfaces/ package" };
+  }
+  if (/\.go$/.test(path) && inAny(path, "handler/", "handlers/", "controller/", "controllers/") && !GO_LEGACY_RE.test(masked)) {
+    return { msg: "Interface in handler file. Move to internal/interfaces/", action: "Move the interface to internal/interfaces/" };
+  }
+  return null;
+}