@mortz.prk/opencode-auto-mode 1.0.1 → 1.0.2

package/src/shell.ts

@@ -1,134 +1,29 @@
-import { parse } from "shell-quote";
-import { basename } from "node:path";
-import { classify } from "./tiers.js";
 import type { ReviewResult } from "./reviewer.js";
+import {
+  BALANCED_QUOTES, CONTROL_OPERATORS, DYNAMIC, REDIRECT_OPERATORS, SCRIPT_HOSTS, SHELLS, STATEFUL,
+  denyCleanPrefix, denyInvocation, hasAmbiguousDescriptorClose, hasAssembledUndecodedSyntax, hasHeredoc,
+  hasUndecodedSyntax, heredocMarkers, isReadOnlyInvocation, logicalLines, normalizeContinuations, parseShell,
+  rawHeredocScript, resolveExecutable, stripDescriptorPrefixes,
+} from "./shell-policy.js";
 
 const MAX_COMMAND_CHARS = 4096;
 const MAX_COMMAND_BYTES = 65_536;
-const BALANCED_QUOTES = /^(?:[^'"\\]|\\[^\r\n]|'[^']*'|"(?:[^"\\]|\\[^\r\n])*")*$/;
-const CONTROL_OPERATORS = new Set([";", "&&", "||", "|", "|&", "&"]);
-const REDIRECT_OPERATORS = new Set([">", ">>", ">&", "<&", "<", "<<", "<<-", "<<<", "<>", ">|", "&>", "&>>"]);
 const WRITE_OPERATORS = new Set([">", ">>", ">|", "&>", "&>>", "<>"]);
-const SHELLS = new Set(["sh", "bash", "dash", "zsh", "ksh", "fish", "pwsh", "powershell", "cmd"]);
-const SCRIPT_HOSTS = new Set(["python", "python3", "node", "perl", "ruby", "php", "awk", "gawk", "lua"]);
-const STATEFUL = new Set(["alias", "unalias", "export", "unset", "set", "shopt", "trap", "umask",
-  "readonly", "declare", "typeset", "local", "function"]);
-const DYNAMIC = new Set(["eval", "source", ".", "exec", "xargs"]);
-const DYNAMIC_SYNTAX = /\$\(|`|\$\(\s*\(|[<>]\(/;
-const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
-const WRAPPERS = new Set(["env", "command", "builtin", "exec", "time", "!", "nohup", "setsid", "nice",
-  "ionice", "stdbuf", "timeout"]);
-const VALUE_OPTIONS = new Set(["-u", "--unset", "-C", "--chdir", "-S", "--split-string", "-a", "--argv0",
-  "-n", "--adjustment", "-s", "--signal", "-k", "--kill-after"]);
-const READ_ONLY = new Set(["pwd", "whoami", "hostname", "uname", "id", "groups", "ls", "cat", "head", "tail",
-  "wc", "date", "echo", "printf", "true", ":", "rg", "grep", "sort", "uniq", "cut", "tr", "jq", "stat", "file",
-  "du", "df", "tree", "bat", "which", "type", "sleep", "test", "basename", "dirname", "realpath", "diff"]);
+const DYNAMIC_SYNTAX = /\$\(|`|\$\(\s*\(|[<>]\(|\$\[/;
+const FORK_BOMB = /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/;
 
 export function shellWords(command: string): string[] | undefined {
   if (!command || command.length > MAX_COMMAND_CHARS || /[$`~\r\n\0{}[\]]/.test(command) ||
       /[^\S \t]/.test(command) || !BALANCED_QUOTES.test(command)) return undefined;
   try {
-    const words = parse(command);
+    const words = parseShell(command);
     return words.length && words.every((word) => typeof word === "string") ? words as string[] : undefined;
   } catch { return undefined; }
 }
 
-interface Segment { words: string[]; write: boolean }
+interface Segment { words: string[]; globs: boolean[]; write: boolean }
 type Verdict = { decision: "deny"; reason: string } | { decision: "allow" | "review" | "ask" };
 
-function blockedCommand(command: string): string | undefined {
-  const normalized = shellWords(command);
-  const result = classify("shell", [command, ...(normalized ? [normalized.join(" ")] : [])]);
-  return result.tier === "auto-deny" ? result.reason : undefined;
-}
-
-/** True when the command contains a heredoc marker outside quotes. Heredoc bodies are data. */
-function hasHeredoc(command: string): boolean {
-  let quote: "'" | '"' | undefined;
-  for (let index = 0; index < command.length; index++) {
-    const character = command[index];
-    if (quote === "'") { if (character === "'") quote = undefined; continue; }
-    if (quote === '"') {
-      if (character === "\\") { index++; continue; }
-      if (character === '"') quote = undefined;
-      continue;
-    }
-    if (character === "'" || character === '"') { quote = character; continue; }
-    if (character === "\\") { index++; continue; }
-    if (character === "<" && command[index + 1] === "<" && command[index + 2] !== "<") return true;
-  }
-  return false;
-}
-
-interface HeredocMarker { delimiter: string; quoted: boolean; stripTabs: boolean }
-
-/** Reads heredoc markers on one line, ignoring markers inside quoted strings and comments. */
-function heredocMarkers(line: string): HeredocMarker[] {
-  const markers: HeredocMarker[] = [];
-  let quote: "'" | '"' | undefined;
-  for (let index = 0; index < line.length; index++) {
-    const character = line[index];
-    if (quote === "'") { if (character === "'") quote = undefined; continue; }
-    if (quote === '"') {
-      if (character === "\\") { index++; continue; }
-      if (character === '"') quote = undefined;
-      continue;
-    }
-    if (character === "'" || character === '"') { quote = character; continue; }
-    if (character === "\\") { index++; continue; }
-    if (character === "#" && (index === 0 || /\s/.test(line[index - 1] ?? ""))) break;
-    if (character !== "<" || line[index + 1] !== "<" || line[index + 2] === "<") continue;
-    let cursor = index + 2;
-    const stripTabs = line[cursor] === "-";
-    if (stripTabs) cursor++;
-    while (line[cursor] === " " || line[cursor] === "\t") cursor++;
-    let delimiter = "";
-    let quoted = false;
-    if (line[cursor] === "'" || line[cursor] === '"') {
-      const closing = line[cursor];
-      quoted = true;
-      cursor++;
-      while (cursor < line.length && line[cursor] !== closing) delimiter += line[cursor++];
-    } else {
-      while (cursor < line.length && /[A-Za-z0-9_]/.test(line[cursor])) delimiter += line[cursor++];
-    }
-    if (delimiter) markers.push({ delimiter, quoted, stripTabs });
-    index = cursor - 1;
-  }
-  return markers;
-}
-
-/** Resolves leading assignments and wrapper options to the effective executable. */
-function resolveExecutable(words: string[]): { name: string; index: number } | undefined {
-  let index = 0;
-  while (index < words.length && ASSIGNMENT.test(words[index])) index++;
-  while (index < words.length) {
-    const name = basename(words[index]);
-    if (!WRAPPERS.has(name)) break;
-    index++;
-    if (name === "timeout") {
-      while (index < words.length && words[index].startsWith("-") && words[index] !== "-") {
-        const option = words[index].split("=", 1)[0];
-        index += VALUE_OPTIONS.has(option) && !words[index].includes("=") ? 2 : 1;
-      }
-      if (index < words.length) index++;
-      continue;
-    }
-    while (index < words.length) {
-      const word = words[index];
-      if (word === "--") { index++; break; }
-      if (word.startsWith("-") && word !== "-") {
-        const option = word.split("=", 1)[0];
-        index += VALUE_OPTIONS.has(option) && !word.includes("=") ? 2 : 1;
-        continue;
-      }
-      if (ASSIGNMENT.test(word)) { index++; continue; }
-      break;
-    }
-  }
-  return index < words.length ? { name: basename(words[index]), index } : undefined;
-}
-
 /** True when the effective executable is a shell, a dynamic builtin, or a stateful builtin. */
 function dynamicExecution(words: string[]): boolean {
   const executable = resolveExecutable(words);
@@ -138,105 +33,184 @@ function dynamicExecution(words: string[]): boolean {
     .some((word) => /^-(?:exec|execdir|ok|okdir|delete)$/.test(word));
 }
 
-function isReadOnlyGit(args: string[]): boolean {
-  if (args.some((arg) =>
-    /^(?:-c|--git-dir|--work-tree|--exec-path|--config-env)(?:=|$)/.test(arg) ||
-    arg === "--ext-diff" || arg === "--exec" || arg.startsWith("--output"))) return false;
-  const subcommand = args[0];
-  if (subcommand === undefined) return false;
-  if (["status", "diff", "log", "show", "rev-parse"].includes(subcommand)) return true;
-  if (subcommand !== "branch") return false;
-  if (args.length === 1) return true;
-  return args.slice(1).every((arg) =>
-    ["--show-current", "--list", "-a", "-r", "-v", "-vv", "--merged", "--no-merged", "--contains", "--points-at", "--format"]
-      .some((safe) => arg === safe || arg.startsWith(`${safe}=`)));
-}
-
-function isReadOnlySed(args: string[]): boolean {
-  if (args.some((arg) => arg === "-i" || arg.startsWith("--in-place") || arg === "-e" ||
-      arg === "--expression" || arg === "-f" || arg === "--file")) return false;
-  return args[0] === "-n" && args[1] !== undefined && /^\d+(?:,\d+)?p$/.test(args[1]);
-}
-
-function isReadOnlyGh(args: string[]): boolean {
-  const [group, subcommand] = args;
-  if (group === "label" && subcommand === "list") return true;
-  if (group === "api") {
-    return !args.some((arg) => arg === "-X" || arg === "--method" || arg.startsWith("-X") ||
-      arg.startsWith("--method=") || ["-f", "--field", "-F", "--raw-field", "--input"].includes(arg));
-  }
-  return new Set(["pr view", "pr list", "pr diff", "pr checks", "issue view", "issue list", "run view",
-    "run list", "repo view", "auth status", "status", "search"]).has(`${group} ${subcommand}`);
-}
-
-function isReadOnly(words: string[]): boolean {
-  const command = basename(words[0]);
-  const args = words.slice(1);
-  if (READ_ONLY.has(command)) {
-    return command !== "date" || !args.some((arg) => arg === "-s" || arg === "--set" || arg.startsWith("--set="));
-  }
-  if (command === "git") return isReadOnlyGit(args);
-  if (command === "find") return !args.some((arg) => /^-(?:fprint|fprint0|fprintf|fls)$/.test(arg));
-  if (command === "sed") return isReadOnlySed(args);
-  if (command === "gh") return isReadOnlyGh(args);
-  if (command === "docker") return args[0] === "logs";
-  if (command === "bun")
-    return args[0] === "test" || (args[0] === "run" && (args[1] === "lint" || args[1] === "typecheck"));
-  return false;
-}
-
 function analyzeSegment(segment: Segment): Verdict {
   if (!segment.words.length) return segment.write ? { decision: "review" } : { decision: "allow" };
   const command = segment.words[0];
   if (!command || command.includes("$")) return { decision: "ask" };
-  const blocked = blockedCommand(segment.words.join(" "));
+  // A deny that is already identifiable wins over every uncertainty below, so
+  // `sudo id *.txt` stays a mandatory deny instead of becoming a review.
+  const blocked = denyInvocation(segment.words);
   if (blocked !== undefined) return { decision: "deny", reason: blocked };
   if (dynamicExecution(segment.words)) return { decision: "ask" };
-  if (!segment.write && isReadOnly(segment.words)) return { decision: "allow" };
+  // `isReadOnlyInvocation` refuses any argument an unquoted expansion could turn
+  // into several words, so the literal flag policies only judge what will run.
+  if (!segment.write && isReadOnlyInvocation(segment.words, segment.globs)) return { decision: "allow" };
   return { decision: "review" };
 }
 
-function analyzeLine(command: string): Verdict {
-  if (!command.trim()) return { decision: "allow" };
-  if (!BALANCED_QUOTES.test(command)) return { decision: "ask" };
-  const blocked = blockedCommand(command);
-  if (blocked !== undefined) return { decision: "deny", reason: blocked };
+/** Token shapes this module consumes; `parse` returns a wider union. */
+type Token = string | { comment: string } | { op: string; pattern?: string };
 
-  let tokens;
-  try { tokens = parse(command); }
-  catch { return { decision: "ask" }; }
-  const blockedTokens = blockedCommand(tokens.filter((token): token is string => typeof token === "string").join(" "));
-  if (blockedTokens !== undefined) return { decision: "deny", reason: blockedTokens };
-  if (DYNAMIC_SYNTAX.test(command)) return { decision: "ask" };
+interface ParsedLine { segments: Segment[]; complete: boolean }
+
+/** Characters that end an unquoted shell word. JS `\s` is wider than a shell, so the set is explicit. */
+const WORD_DELIMITER = /[ \t\n;|&()<>]/;
+
+/**
+ * One entry per shell word, true when the word contains an expansion that can
+ * turn it into several arguments.
+ *
+ * `shell-quote` only marks `*` and `?` as globs, but bracket (`[ab]`) and brace
+ * (`{a,b}`) expansion, and parameter expansion, change the argument count too.
+ * This scan is quote- and escape-aware, so quoted or escaped bracket, brace, and
+ * glob markers are not flagged here. `shell-quote` still reports an escaped
+ * `*`/`?` as a glob token, which stays conservatively reviewed.
+ *
+ * A parameter inside double quotes counts as uncertain for the same reason: it
+ * stays one word only after expansion, and the value decides both the text and —
+ * for `"$@"` — the count. `sort "${X:--oout}" file` writes a file when `X` is
+ * unset, `find . "${X:--delete}"` deletes, and `uniq "$@"` can become two
+ * operands, while `shell-quote` sees only an empty string. Single quotes and an
+ * escaped `\$` are literal and stay safe. Matching the flags by position keeps
+ * the raw text out of the parsed logic.
+ */
+function wordExpansions(command: string): boolean[] {
+  const expansions: boolean[] = [];
+  let present = false;
+  let expansion = false;
+  let wordStart = true;
+  let quote: "'" | '"' | "$'" | undefined;
+  const flush = () => {
+    if (!present) return;
+    expansions.push(expansion);
+    present = false;
+    expansion = false;
+  };
+  for (let index = 0; index < command.length; index++) {
+    const character = command[index];
+    if (quote === "'") {
+      if (character === "'") quote = undefined;
+      continue;
+    }
+    if (quote === "$'") {
+      if (character === "\\") index++;
+      else if (character === "'") quote = undefined;
+      continue;
+    }
+    if (quote === '"') {
+      if (character === "\\") index++;
+      else if (character === '"') quote = undefined;
+      else if (character === "$") expansion = true;
+      continue;
+    }
+    if (character === "\\") {
+      present = true;
+      if (index + 1 < command.length && command[++index] !== "\n") wordStart = false;
+      continue;
+    }
+    if (character === "'" || character === '"' || (character === "$" && command[index + 1] === "'")) {
+      present = true;
+      wordStart = false;
+      if (character === "'" || character === '"') quote = character;
+      else { quote = "$'"; index++; }
+      continue;
+    }
+    if (character === "#" && wordStart) {
+      const end = command.indexOf("\n", index);
+      flush();
+      if (end === -1) break;
+      index = end;
+      wordStart = true;
+      continue;
+    }
+    if (WORD_DELIMITER.test(character)) {
+      flush();
+      wordStart = true;
+      continue;
+    }
+    if (character === "*" || character === "?" || character === "[" || character === "{" ||
+        character === "$") expansion = true;
+    present = true;
+    wordStart = false;
+  }
+  flush();
+  return expansions;
+}
 
-  const segments: Segment[] = [{ words: [], write: false }];
+/** Splits parsed tokens into simple commands, tracking whether the whole line parsed. */
+function lineSegments(tokens: readonly Token[], expansions: readonly boolean[] = []): ParsedLine {
+  const segments: Segment[] = [{ words: [], globs: [], write: false }];
   let current = segments[0];
   let redirect: { write: boolean } | undefined;
+  let wordIndex = 0;
+  const nextExpansion = () => expansions[wordIndex++] ?? false;
   for (const token of tokens) {
     if (typeof token === "string") {
       if (redirect) {
         const target = token;
+        nextExpansion();
         if (redirect.write && target !== "/dev/null" && !/^\d+$/.test(target) && !target.startsWith("&"))
           current.write = true;
         redirect = undefined;
-      } else current.words.push(token);
+      } else {
+        current.words.push(token);
+        current.globs.push(nextExpansion());
+      }
       continue;
     }
     if ("comment" in token) continue;
-    if (token.op === "glob") { current.words.push(token.pattern); continue; }
+    if (token.op === "glob" && token.pattern !== undefined) {
+      if (redirect) {
+        // A glob is still a redirection target, so it never becomes a command word.
+        nextExpansion();
+        if (redirect.write) current.write = true;
+        redirect = undefined;
+      } else {
+        nextExpansion();
+        current.words.push(token.pattern);
+        current.globs.push(true);
+      }
+      continue;
+    }
     if (CONTROL_OPERATORS.has(token.op)) {
-      current = { words: [], write: false };
+      // A control operator before the redirection target is invalid syntax.
+      if (redirect) return { segments, complete: false };
+      current = { words: [], globs: [], write: false };
       segments.push(current);
       continue;
     }
     if (REDIRECT_OPERATORS.has(token.op)) {
-      if (current.words.length && /^\d+$/.test(current.words[current.words.length - 1])) current.words.pop();
+      // Descriptor prefixes (`2>` in `2>/dev/null`) are stripped from the source
+      // before parsing, so a numeric word here is an operand and must survive.
       redirect = { write: WRITE_OPERATORS.has(token.op) };
       continue;
     }
-    return { decision: "ask" };
+    return { segments, complete: false };
   }
-  if (redirect) return { decision: "ask" };
+  return { segments, complete: redirect === undefined };
+}
+
+function analyzeLine(command: string): Verdict {
+  if (!command.trim()) return { decision: "allow" };
+  if (!BALANCED_QUOTES.test(command)) return { decision: "ask" };
+  if (FORK_BOMB.test(command)) return { decision: "deny", reason: "dangerous shell operation" };
+
+  let tokens;
+  try { tokens = parseShell(command); }
+  catch { return { decision: "ask" }; }
+
+  const { segments, complete } = lineSegments(tokens, wordExpansions(stripDescriptorPrefixes(command)));
+  // Deny rules that are already visible must win even when later arguments are
+  // dynamic (`sudo id $(...)`) and even when the line only parses partially.
+  for (const segment of segments) {
+    const blocked = denyInvocation(segment.words);
+    if (blocked !== undefined) return { decision: "deny", reason: blocked };
+  }
+  // Bash closes the descriptor and runs the rest of the word as a command
+  // (`2>&-sudo id` runs sudo), while shell-quote reads `-sudo` as the redirect
+  // target. Neither reading may approve the invocation.
+  if (hasAmbiguousDescriptorClose(command)) return { decision: "ask" };
+  if (!complete || DYNAMIC_SYNTAX.test(command)) return { decision: "ask" };
 
   let ask = false;
   let review = false;
@@ -250,6 +224,26 @@ function analyzeLine(command: string): Verdict {
   return { decision: review ? "review" : "allow" };
 }
 
+/** Analyzes every logical line, keeping deny precedence over ask and review. */
+function analyzeLines(command: string): Verdict {
+  let ask = false;
+  let review = false;
+  const { lines, certain } = logicalLines(command);
+  // An undecodable header or a body that can move its terminator leaves the
+  // script/data split unknown, so nothing past that line may be auto-approved.
+  if (certain < lines.length) ask = true;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const verdict = analyzeLine(trimmed);
+    if (verdict.decision === "deny") return verdict;
+    if (verdict.decision === "ask") ask = true;
+    else if (verdict.decision === "review") review = true;
+  }
+  if (ask) return { decision: "ask" };
+  return { decision: review ? "review" : "allow" };
+}
+
 function analyzeHeredoc(command: string): Verdict {
   const lines = command.split("\n");
   const firstLine = lines[0] ?? "";
@@ -270,48 +264,98 @@ function analyzeHeredoc(command: string): Verdict {
     bodies.push({ lines: body, quoted: marker.quoted });
   }
 
-  let ask = false;
-  let review = false;
-  for (const line of [firstLine, ...lines.slice(index)]) {
-    if (!line.trim()) continue;
-    const verdict = analyzeLine(line);
-    if (verdict.decision === "deny") return verdict;
-    if (verdict.decision === "ask") ask = true;
-    else if (verdict.decision === "review") review = true;
+  // The header line is script, and so is the text after the bodies — but only if
+  // the bodies really end where the raw text says. The header is analyzed on its
+  // own because its markers have already been consumed above: handing them back
+  // to the heredoc scanner would swallow the tail as a second body.
+  const header = analyzeLine(firstLine);
+  if (header.decision === "deny") return header;
+  // An unquoted body is matched against its terminator after the shell removes
+  // continuations, so a body line ending in a backslash moves the boundary —
+  // including the last one, whose `\`-newline joins the terminator line into the
+  // body. That has to fail closed before the tail is judged, or a tail that is
+  // really body data would deny. A quoted body keeps its backslashes literally.
+  for (const body of bodies) {
+    if (body.quoted) continue;
+    if (body.lines.some((line) => line.endsWith("\\"))) return { decision: "ask" };
   }
+  // The tail is analyzed as its own script so a further heredoc there is routed
+  // the same way, and a blocked command spanning a quoted newline is still seen
+  // whole.
+  const tail = lines.slice(index).join("\n");
+  const rest: Verdict = tail ? analyze(tail) : { decision: "allow" };
+  if (rest.decision === "deny") return rest;
+  let ask = header.decision === "ask" || rest.decision === "ask";
+  const review = header.decision === "review" || rest.decision === "review";
+  // Unquoted heredoc bodies undergo command and parameter expansion. That can run
+  // a substitution, so it fails closed, but it cannot move the terminator: the
+  // tail denied above stays a deny.
   for (const body of bodies) {
-    // Unquoted heredoc bodies undergo command and parameter expansion.
-    if (!body.quoted && DYNAMIC_SYNTAX.test(body.lines.join("\n"))) return { decision: "ask" };
+    if (body.quoted) continue;
+    if (DYNAMIC_SYNTAX.test(body.lines.join("\n"))) return { decision: "ask" };
   }
   try {
-    const words = parse(firstLine).filter((token): token is string => typeof token === "string");
+    const words = parseShell(firstLine).filter((token): token is string => typeof token === "string");
     const executable = resolveExecutable(words);
     if (executable === undefined || SHELLS.has(executable.name) || SCRIPT_HOSTS.has(executable.name) ||
-        DYNAMIC.has(executable.name) || STATEFUL.has(executable.name)) return { decision: "ask" };
+        DYNAMIC.has(executable.name) || STATEFUL.has(executable.name)) ask = true;
   } catch { return { decision: "ask" }; }
   if (ask) return { decision: "ask" };
   return { decision: review ? "review" : "allow" };
 }
 
 function analyze(command: string): Verdict {
-  if (hasHeredoc(command)) return analyzeHeredoc(command);
-  const blocked = blockedCommand(command);
-  if (blocked !== undefined) return { decision: "deny", reason: blocked };
-  if (command.includes("\n")) {
-    let ask = false;
-    let review = false;
-    for (const line of command.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
-      const verdict = analyzeLine(trimmed);
+  // A shell separates words only on space, tab, and newline. JS `\s` (and the
+  // parser behind it) also matches CR, FF, VT, NBSP, and Unicode spaces, which
+  // can move a heredoc boundary or turn a midword hash into a comment, so any of
+  // them fails closed before normalization, the deny pass, or parsing.
+  //
+  // `$[` is the legacy arithmetic expansion: the `<<` inside it is a shift, not
+  // a heredoc, so heredoc routing would treat the rest of the script as a body
+  // and swallow a trailing command. Extended quoting has the same problem from
+  // the other side: `$'...'` lets a backslash escape its own quote, so a quote
+  // scan can end the string early and read `<<EOF` as a heredoc, and `$"..."`
+  // is a locale quote this parser does not decode. Reject all three on the raw
+  // source before normalization or heredoc routing, conservatively including
+  // quoted and heredoc data.
+  if (hasUndecodedSyntax(command)) return { decision: "ask" };
+  // Fail closed on any raw heredoc header that normalization cannot be trusted
+  // on: the raw source is the only place its marker and delimiter are still
+  // intact. Every header is validated, not just the first, because a continued
+  // header after a stable body is the same problem. Each raw line before the
+  // ambiguity is certainly script — the header line itself runs before the shell
+  // reads its body — so a deny visible there is mandatory; everything after may
+  // be data and only reaches manual approval.
+  const raw = rawHeredocScript(command);
+  if (raw.ambiguous) {
+    for (const line of raw.lines) {
+      // A line whose own normalization assembles unsupported quoting cannot be
+      // parsed safely; its deny is left to manual approval instead of guessed.
+      if (hasAssembledUndecodedSyntax(line)) continue;
+      // The raw line may still carry a `\`-newline that the shell removes before
+      // it forms this header; removing it here only reaches the deny pass, and
+      // the header line itself is always script.
+      const verdict = analyzeLine(normalizeContinuations(line).trim());
       if (verdict.decision === "deny") return verdict;
-      if (verdict.decision === "ask") ask = true;
-      else if (verdict.decision === "review") review = true;
     }
-    if (ask) return { decision: "ask" };
-    return { decision: review ? "review" : "allow" };
+    return { decision: "ask" };
   }
-  return analyzeLine(command);
+  // Normalization removes `\`-newlines, so the shell can parse an unsupported
+  // form the raw check above could not see: `sort $`+newline+`'\x2doout'` is
+  // `sort -oout` to Bash once the pair is gone. The marker itself is never parsed.
+  // A deny in the clean prefix before it is still mandatory, so check that first;
+  // only then repeat the gate and fail closed before heredoc routing.
+  const normalized = normalizeContinuations(command);
+  if (hasUndecodedSyntax(normalized)) {
+    const blocked = denyCleanPrefix(normalized);
+    if (blocked !== undefined) return { decision: "deny", reason: blocked };
+    return { decision: "ask" };
+  }
+  // `logicalLines` must split on the newlines the shell actually treats as
+  // separators, and heredoc bodies stay untouched.
+  if (hasHeredoc(normalized)) return analyzeHeredoc(normalized);
+  if (normalized.includes("\n")) return analyzeLines(normalized);
+  return analyzeLine(normalized);
 }
 
 export function guardShell(resources: readonly string[]): ReviewResult | undefined {
@@ -330,3 +374,22 @@ export function guardShell(resources: readonly string[]): ReviewResult | undefin
   if (ask) return { decision: "ask", reason: "Shell syntax requires manual approval" };
   return review ? undefined : { decision: "allow", reason: "read-only command" };
 }
+
+export interface ShellClassification {
+  tier: "auto-allow" | "auto-deny" | "review";
+  reason: string;
+}
+
+/**
+ * Static tier classification for shell actions. The shell guard is the single
+ * source of truth so the classifier can never allow or deny something the guard
+ * would not.
+ */
+export function classifyShell(resources: readonly string[]): ShellClassification {
+  const verdict = guardShell(resources);
+  if (verdict?.decision === "deny") return { tier: "auto-deny", reason: verdict.reason };
+  if (verdict?.decision === "allow") return { tier: "auto-allow", reason: verdict.reason };
+  if (verdict?.decision === "ask") return { tier: "review", reason: "shell syntax requires manual approval" };
+  return { tier: "review", reason: "evaluate the entire command as one action" };
+}
+

package/src/status.ts

@@ -0,0 +1,72 @@
+import type { AutoModeDecision, AutoModeStatus } from "./rpc.js";
+
+const MAX_RECENT = 100;
+// Match the audit record bounds so live status and durable history describe
+// the same action, not an unbounded copy of the permission event.
+const MAX_ACTION_CHARS = 128;
+const MAX_STAGE_CHARS = 64;
+const MAX_REASON_CHARS = 200;
+const MAX_REVIEWING = 256;
+
+function clip(value: string, max = MAX_REASON_CHARS): string {
+  // Count code points, not UTF-16 units, so clipping cannot cut a surrogate
+  // pair in half.
+  const characters = Array.from(value);
+  return characters.length > max ? `${characters.slice(0, max - 1).join("")}…` : value;
+}
+
+export interface StatusTracker {
+  start(sessionID: string, reviewID: string, at: number): void;
+  finish(decision: Omit<AutoModeDecision, "reason"> & { reason: string }): AutoModeDecision;
+  snapshot(input: { enabled: boolean; configError?: string; classifiers: string[]; reviewTimeoutMs: number; sessionID?: string }): AutoModeStatus;
+  recent(limit: number, sessionID?: string): AutoModeDecision[];
+}
+
+/**
+ * Small in-memory view of AutoMode for clients. It holds no prompts and is
+ * bounded in both entries and text so a long session cannot grow it without
+ * limit; durable history stays in the audit log.
+ */
+export function createStatusTracker(): StatusTracker {
+  // Keyed by review rather than session: a session can ask about several
+  // actions at once, and finishing one must not hide the others.
+  const reviewing = new Map<string, { sessionID: string; startedAt: number }>();
+  let recent: AutoModeDecision[] = [];
+
+  return {
+    start(sessionID, reviewID, at) {
+      if (reviewing.size >= MAX_REVIEWING && !reviewing.has(reviewID)) {
+        const oldest = reviewing.keys().next().value;
+        if (oldest !== undefined) reviewing.delete(oldest);
+      }
+      reviewing.set(reviewID, { sessionID, startedAt: at });
+    },
+    finish(decision) {
+      reviewing.delete(decision.reviewID);
+      const entry: AutoModeDecision = {
+        ...decision,
+        action: clip(decision.action, MAX_ACTION_CHARS),
+        stage: clip(decision.stage, MAX_STAGE_CHARS),
+        reason: clip(decision.reason),
+      };
+      recent = [...recent, entry].slice(-MAX_RECENT);
+      return entry;
+    },
+    snapshot(input) {
+      return {
+        enabled: input.enabled,
+        ...(input.configError === undefined ? {} : { configError: clip(input.configError) }),
+        classifiers: input.classifiers,
+        reviewTimeoutMs: input.reviewTimeoutMs,
+        reviewing: [...reviewing.entries()]
+          .filter(([, entry]) => input.sessionID === undefined || entry.sessionID === input.sessionID)
+          .map(([reviewID, entry]) => ({ sessionID: entry.sessionID, reviewID, startedAt: entry.startedAt })),
+        recent: input.sessionID === undefined ? recent.slice(-20) : recent.filter((entry) => entry.sessionID === input.sessionID).slice(-20),
+      };
+    },
+    recent(limit, sessionID) {
+      const matches = sessionID === undefined ? recent : recent.filter((entry) => entry.sessionID === sessionID);
+      return matches.slice(-limit);
+    },
+  };
+}