pi-roundtable 0.22.4 → 0.23.0

package/src/core/modules/host-shell/shell-policy.ts

@@ -1,17 +1,37 @@
 import { basename } from "node:path";
 import type { HoldContext, HoldRule } from "../../holds.ts";
-import { assistantName } from "../../i18n/index.ts";
-import { ownPush, type PushPolicy } from "./git-push.ts";
+import type { PushPolicy } from "./git-push.ts";
+import { COMMAND_PREFIX_WORDS, EXPANDED, lexShell } from "./shell-lexer.ts";
 import {
+	bindingCounts,
+	deviceTarget,
+	expand,
+	expandName,
 	follow,
-	insideRoots,
+	forgetRebound,
 	type LineState,
 	lineState,
-	resolvePath,
 	rmHeld,
+	writable,
 } from "./shell-paths.ts";
+import { type Held, type ShellClass, verbHeld } from "./shell-programs.ts";
+import {
+	readsUnseenScript,
+	recordWrites,
+	SHELLS,
+	shellScript,
+	teeOperands,
+} from "./shell-scripts.ts";
+import {
+	ASSIGNMENT_WORD,
+	program,
+	replaceString,
+	WRAPPERS,
+} from "./shell-wrappers.ts";
 
 export type { PushPolicy } from "./git-push.ts";
+export { simpleCommands } from "./shell-lexer.ts";
+export { YOLO_CARDED_SHELL_CLASSES } from "./shell-programs.ts";
 
 const MAX_SHOWN_COMMAND = 600;
 
@@ -23,376 +43,311 @@ export const SHELL_TOOLS = Object.freeze([
 	"write",
 ] as const);
 
-/** Programs that are held whatever their arguments. */
-const ALWAYS_HELD = new Set([
-	"sudo",
-	"su",
-	"doas",
-	"dd",
-	"shutdown",
-	"reboot",
-	"poweroff",
-	"halt",
-	"kill",
-	"pkill",
-	"killall",
-]);
-const SYSTEMD_VERBS = new Set([
-	"start",
-	"stop",
-	"restart",
-	"reload",
-	"try-restart",
-	"reload-or-restart",
-	"enable",
-	"disable",
-	"mask",
-	"unmask",
-	"kill",
-	"isolate",
-]);
-const DOCKER_VERBS = new Set(["stop", "kill", "restart", "rm", "rmi", "prune"]);
-const DOCKER_OBJECTS = new Set([
-	"container",
-	"image",
-	"volume",
-	"network",
-	"system",
-	"builder",
-]);
-const COMPOSE_VERBS = new Set(["down", "stop", "kill", "restart", "rm"]);
-const PACKAGE_VERBS = new Set([
-	"install",
-	"reinstall",
-	"remove",
-	"purge",
-	"autoremove",
-	"upgrade",
-	"full-upgrade",
-	"dist-upgrade",
-]);
-/** Words that run the next word as the command. */
-const WRAPPERS = new Set([
-	"env",
-	"nohup",
-	"time",
-	"nice",
-	"ionice",
-	"timeout",
-	"stdbuf",
-	"exec",
-	"command",
-	"xargs",
-]);
+/** The words the lexer gives a redirection operator. */
+const REDIRECTS: ReadonlySet<string> = new Set(["<", ">", ">>", "dup"]);
+
+/** Why a command whose name is not known until it runs is held. */
+const DYNAMIC_NAME: Held = {
+	reason: "a command whose name is built at run time",
+	class: "shell.unreadable",
+};
 
 /**
- * Whether a write to the word stays inside a scratch root. A word the line cannot resolve is read
- * as written from the workspace, as before variables were followed.
+ * The program a command word names, or undefined when the word expands to more than the line says:
+ * a variable not known, a substitution, a brace expansion or a pattern (`$cmd`, `{sudo,ls}`,
+ * `/usr/bin/sud*`).
  */
-function writable(word: string, state: LineState): boolean {
-	if (word === "/dev/null") return true;
-	const path =
-		resolvePath(word, state) ??
-		resolvePath(word, { ...state, vars: new Map(), cwd: state.workspace }) ??
-		word;
-	return insideRoots(path, state);
+function commandName(word: string, state: LineState): string | undefined {
+	// `[` and `[[` are the test commands, not patterns.
+	if (word !== "[" && word !== "[[" && /[*?[]/.test(word)) return undefined;
+	if (/\{[^{}]*(?:,|\.\.)[^{}]*\}/.test(word)) return undefined;
+	return word.includes("$") || word.includes("`")
+		? expandName(word, state)
+		: word;
 }
 
-/** Splits a command line into simple commands of words; quotes are removed, operators separate. */
-export function simpleCommands(command: string): string[][] {
-	const commands: string[][] = [];
-	let words: string[] = [];
-	let word = "";
-	let inWord = false;
-	let quote: "'" | '"' | undefined;
-	const endWord = () => {
-		if (inWord) words.push(word);
-		word = "";
-		inWord = false;
-	};
-	const endCommand = () => {
-		endWord();
-		if (words.length > 0) commands.push(words);
-		words = [];
-	};
-	for (let i = 0; i < command.length; i++) {
-		const ch = command[i] as string;
-		if (quote) {
-			if (ch === quote) quote = undefined;
-			else if (ch === "\\" && quote === '"' && i + 1 < command.length) {
-				word += command[++i];
-			} else word += ch;
-			continue;
-		}
-		if (ch === "'" || ch === '"') {
-			quote = ch;
-			inWord = true;
-		} else if (ch === "\\" && i + 1 < command.length) {
-			word += command[++i];
-			inWord = true;
-		} else if (/\s/.test(ch)) {
-			if (ch === "\n") endCommand();
-			else endWord();
-		} else if (";&|()`{}".includes(ch)) {
-			// A word cut by a command substitution keeps its mark, so its value counts as unknown.
-			if (ch === "`" && inWord) word += ch;
-			endCommand();
-		} else if (ch === "$" && command[i + 1] === "(") {
-			if (inWord) word += "$(";
-			endCommand();
-			i++;
-		} else if (ch === ">" || ch === "<") {
-			// Redirections become their own words, so their targets can be checked.
-			endWord();
-			let op = ch;
-			if (command[i + 1] === ">") op += command[++i];
-			if (command[i + 1] === "&") {
-				// `>&2` duplicates a descriptor rather than naming a file.
-				i++;
-				op = "dup";
-			}
-			words.push(op);
-		} else {
-			word += ch;
-			inWord = true;
-		}
-	}
-	endCommand();
-	return commands;
-}
+/** Variables whose value bash runs as a command or expands with substitutions on its own. */
+const SELF_RUNNING_VARIABLE =
+	/^(?:PROMPT_COMMAND|PS[0124]|BASH_ENV|ENV|SHELLOPTS|BASH_ALIASES\[.*\])\+?=/;
+
+/** Builtins whose arguments can be assignments. */
+const ASSIGNING = new Set([
+	"export",
+	"declare",
+	"typeset",
+	"local",
+	"readonly",
+	"env",
+]);
 
 /**
- * Drops leading variable assignments, wrappers, and their options, leaving the real program;
- * `prefix` collects what was dropped.
+ * Whether the command sets a variable that makes a shell run something later: before the command
+ * (`PS4='$(x)' bash -x`) or as an argument of `export`, `declare` and the like.
  */
-function program(words: string[], prefix: string[] = []): string[] {
-	let rest = words;
-	for (;;) {
-		const [first] = rest;
-		if (first === undefined) return rest;
-		if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(first)) {
-			prefix.push(first);
-			rest = rest.slice(1);
-			continue;
-		}
-		if (WRAPPERS.has(basename(first))) {
-			prefix.push(basename(first));
-			rest = rest.slice(1);
-			// Wrapper options and the timeout's duration.
-			while (
-				rest[0] !== undefined &&
-				(rest[0].startsWith("-") ||
-					/^\d+[smhd]?$/.test(rest[0]) ||
-					/^[A-Za-z_][A-Za-z0-9_]*=/.test(rest[0]))
-			)
-				rest = rest.slice(1);
-			continue;
-		}
-		return rest;
+function setsSelfRunningVariable(words: readonly string[]): boolean {
+	for (const word of words) {
+		if (SELF_RUNNING_VARIABLE.test(word)) return true;
+		const name = basename(word);
+		if (
+			!/^[A-Za-z_][A-Za-z0-9_]*(?:\[.*\])?\+?=/.test(word) &&
+			!word.startsWith("-") &&
+			!COMMAND_PREFIX_WORDS.has(word) &&
+			!WRAPPERS.has(name) &&
+			!ASSIGNING.has(name)
+		)
+			return false;
 	}
+	return false;
 }
 
-/** Why one simple command is held, or undefined; reads the line's state as it is before it. */
-function heldReason(
+/** Builtins whose arguments can name a variable with a subscript, such as `a[$(x)]`, which bash evaluates. */
+const SUBSCRIPT_EVALUATORS = new Set([
+	"declare",
+	"typeset",
+	"local",
+	"readonly",
+	"export",
+	"printf",
+	"read",
+	"unset",
+	"mapfile",
+	"readarray",
+	"getopts",
+	"wait",
+	"test",
+	"[",
+	"[[",
+	"let",
+]);
+
+/** The script a `trap` command installs, or undefined when it only lists or clears traps. */
+function trapScript(args: readonly string[]): string | undefined {
+	const rest = [...args];
+	while (rest[0]?.startsWith("-")) if (rest.shift() === "--") break;
+	const [script] = rest;
+	return rest.length > 1 && script !== "" && script !== "-"
+		? script
+		: undefined;
+}
+
+/** The command `find` runs for each match (`-exec`, `-execdir`, `-ok`, `-okdir`), up to its `;` or `+`. */
+function findExec(args: readonly string[]): string[] | undefined {
+	const at = args.findIndex((arg) => /^-(exec|execdir|ok|okdir)$/.test(arg));
+	if (at === -1) return undefined;
+	const rest = args.slice(at + 1);
+	const stop = rest.findIndex((arg) => arg === ";" || arg === "+");
+	return stop === -1 ? rest : rest.slice(0, stop);
+}
+
+/** The class of each program that is held whatever its arguments. */
+const ALWAYS_HELD_CLASS: ReadonlyMap<string, ShellClass> = new Map([
+	["sudo", "shell.privilege"],
+	["su", "shell.privilege"],
+	["doas", "shell.privilege"],
+	["dd", "shell.disk"],
+	["shutdown", "shell.power"],
+	["reboot", "shell.power"],
+	["poweroff", "shell.power"],
+	["halt", "shell.power"],
+	["kill", "shell.kill"],
+	["pkill", "shell.kill"],
+	["killall", "shell.kill"],
+]);
+
+/** Every reason one simple command is held, the redirections first; reads the line's state as it is before it. */
+function heldReasons(
 	words: string[],
 	state: LineState,
 	policy: PushPolicy,
-): string | undefined {
+): Held[] {
+	const found: Held[] = [];
 	for (let i = 0; i < words.length; i++) {
 		const op = words[i];
 		if (op === ">" || op === ">>") {
 			const target = words[i + 1];
-			if (target && !writable(target, state)) return `writes to ${target}`;
+			if (target && !writable(target, state))
+				found.push({
+					reason: `writes to ${target}`,
+					class: deviceTarget(target, state) ? "shell.disk" : "shell.write",
+				});
 		}
 	}
+	return [...found, ...programHeld(words, state, policy)];
+}
+
+/** Why the program a simple command runs is held, apart from its redirections. */
+function programHeld(
+	words: string[],
+	state: LineState,
+	policy: PushPolicy,
+): Held[] {
 	const prefix: string[] = [];
-	const argv = program(
-		words.filter(
-			(w, i) =>
-				!["<", ">", ">>", "dup"].includes(w) &&
-				!["<", ">", ">>"].includes(words[i - 1] ?? ""),
-		),
-		prefix,
+	// A redirection is no part of the command: not its operator nor its target.
+	const own = words.filter(
+		(w, i) => !REDIRECTS.has(w) && !REDIRECTS.has(words[i - 1] ?? ""),
 	);
-	const [head, ...args] = argv;
-	if (!head) return undefined;
+	const argv = program(own, prefix);
+	// A prompt or a startup file that runs a command needs no command word of its own
+	// (`PS4='$(x)'; set -x`), and `env -S` splits its argument into a command line.
+	if (setsSelfRunningVariable(own) || prefix.includes("env -S"))
+		return [DYNAMIC_SCRIPT];
+	const [word, ...args] = argv;
+	// `xargs env` runs what its input says.
+	if (!word)
+		return prefix.includes("xargs") && prefix.at(-1) !== "xargs"
+			? [DYNAMIC_SCRIPT]
+			: [];
+	const head = commandName(word, state);
+	if (head === undefined) {
+		// A variable the line binds may be empty when bash gets there, so the name is unknown; what
+		// the line gives it is still judged, so the card says what it would run.
+		const guess = word.includes("$") ? expand(word, state) : undefined;
+		return [
+			...(guess === undefined
+				? []
+				: programHeld([guess, ...args], state, policy)),
+			DYNAMIC_NAME,
+		];
+	}
 	const name = basename(head);
-	if (ALWAYS_HELD.has(name) || /^mkfs(\..+)?$/.test(name)) return name;
-	if (name === "rm")
+	// A command or a script `xargs` fills in from its input, or one the line does not show.
+	const replace = replaceString(prefix);
+	if (
+		(replace !== undefined &&
+			(word.includes(replace) ||
+				(SHELLS.has(name) && args.some((arg) => arg.includes(replace))))) ||
+		readsUnseenScript(word, name, args, prefix, state)
+	)
+		return [DYNAMIC_SCRIPT];
+	// `mapfile -C` runs a callback for every chunk it reads.
+	if (
+		(name === "mapfile" || name === "readarray") &&
+		args.some((arg) => /^-[A-Za-z]*C/.test(arg))
+	)
+		return [DYNAMIC_SCRIPT];
+	// A builtin that takes a name evaluates a subscript in it, and that runs a substitution.
+	if (
+		SUBSCRIPT_EVALUATORS.has(name) &&
+		args.some((arg) => /\[[^\]]*(?:\$\(|`)/.test(arg))
+	)
+		return [DYNAMIC_SCRIPT];
+	// An alias names a command at run time; `expand_aliases` is what lets a script use one.
+	if (name === "alias" && args.some((arg) => arg.includes("=")))
+		return [DYNAMIC_NAME];
+	if (name === "trap") {
+		const script = trapScript(args);
+		if (script !== undefined) return scriptHeld(script, state, policy);
+	}
+	const always = ALWAYS_HELD_CLASS.get(name);
+	if (always) return [{ reason: name, class: always }];
+	if (/^mkfs(\..+)?$/.test(name))
+		return [{ reason: name, class: "shell.disk" }];
+	if (name === "rm") {
 		// xargs adds operands nobody can see here.
-		return prefix.includes("xargs") ? "rm" : rmHeld(args, state);
-	if ((name === "bash" || name === "sh" || name === "zsh") && args[0] === "-c")
-		return commandHeld(args[1] ?? "", state, policy);
-	const verbs = args.filter((a) => !a.startsWith("-"));
-	switch (name) {
-		case "systemctl":
-			return verbs.some((v) => SYSTEMD_VERBS.has(v))
-				? "changes a systemd unit"
-				: undefined;
-		case "service":
-			return verbs.some((v) =>
-				["start", "stop", "restart", "reload"].includes(v),
-			)
-				? "changes a service"
-				: undefined;
-		case "docker": {
-			const [first, second] = verbs;
-			if (first === "compose")
-				return second && COMPOSE_VERBS.has(second)
-					? `docker compose ${second}`
-					: undefined;
-			if (first && DOCKER_VERBS.has(first)) return `docker ${first}`;
-			if (
-				first &&
-				DOCKER_OBJECTS.has(first) &&
-				second &&
-				(DOCKER_VERBS.has(second) || second === "remove")
-			)
-				return `docker ${first} ${second}`;
-			return undefined;
-		}
-		case "docker-compose":
-			return verbs[0] && COMPOSE_VERBS.has(verbs[0])
-				? `docker-compose ${verbs[0]}`
-				: undefined;
-		case "ufw":
-			return verbs[0] === "status" || verbs.length === 0
-				? undefined
-				: "changes the firewall";
-		case "iptables":
-		case "ip6tables":
-		case "nft":
-			return args.some((a) => ["-L", "--list", "-S", "list"].includes(a))
-				? undefined
-				: "changes the firewall";
-		case "apt":
-		case "apt-get":
-		case "snap":
-			return verbs.some((v) => PACKAGE_VERBS.has(v))
-				? "installs or removes packages"
-				: undefined;
-		case "dpkg":
-			return args.some((a) =>
-				["-i", "-r", "-P", "--install", "--remove", "--purge"].includes(a),
-			)
-				? "installs or removes packages"
-				: undefined;
-		case "git": {
-			const [globals, [verb, ...rest]] = gitCommand(args);
-			if (verb === "push") {
-				const plain = !prefix.some((w) => w.startsWith("GIT_"));
-				if (plain && ownPush(globals, rest, state, policy)) return undefined;
-				return rest.some((a) => a === "-f" || a.startsWith("--force"))
-					? "force-pushes"
-					: `pushes to GitHub, which deploys ${assistantName()} when the branch is main`;
-			}
-			if (verb === "reset" && rest.includes("--hard"))
-				return "git reset --hard";
-			return undefined;
-		}
-		case "gh":
-			return ghHeld(args);
-		case "crontab":
-			return args.includes("-r") ? "removes a crontab" : undefined;
-		case "tee": {
-			const target = args.find(
-				(a) => !a.startsWith("-") && !writable(a, state),
-			);
-			return target ? `writes to ${target}` : undefined;
-		}
-		default:
-			return undefined;
+		const reason = prefix.includes("xargs") ? "rm" : rmHeld(args, state);
+		return reason ? [{ reason, class: "shell.rm" }] : [];
+	}
+	if (name === "eval") {
+		// What eval runs is its arguments after expansion: all of them must be known.
+		const known = args.map((arg) => expandName(arg, state));
+		return known.includes(undefined)
+			? [DYNAMIC_SCRIPT]
+			: commandHeld(known.join(" "), state, policy);
 	}
+	if (SHELLS.has(name)) {
+		const script = shellScript(args);
+		if (script !== undefined) return scriptHeld(script, state, policy);
+	}
+	if (name === "find") {
+		const exec = findExec(args);
+		if (exec) return programHeld(exec, state, policy);
+	}
+	const held = verbHeld(name, args, prefix, state, policy);
+	return held ? [held] : [];
 }
 
-/** Git's global options that take a value, as separate words. */
-const GIT_VALUE_OPTIONS = new Set([
-	"-C",
-	"-c",
-	"--git-dir",
-	"--work-tree",
-	"--namespace",
-]);
-
-/** Git's global options, such as `-C <dir>`, and the subcommand with its arguments. */
-function gitCommand(args: string[]): [string[], string[]] {
-	let i = 0;
-	while (i < args.length && (args[i] as string).startsWith("-"))
-		i += GIT_VALUE_OPTIONS.has(args[i] as string) ? 2 : 1;
-	return [args.slice(0, i), args.slice(i)];
+/** Whether a simple command evaluates arithmetic without `(( ))`: `let`, `declare -i`, `[[ a -eq b ]]`. */
+function evaluatesArithmetic(words: readonly string[]): boolean {
+	const [first] = words;
+	if (first === "let") return true;
+	if (first === "declare" || first === "typeset" || first === "local")
+		return words.some((word) => /^-[A-Za-z]*i/.test(word));
+	return (
+		first === "[[" &&
+		words.some((word) => /^-(?:eq|ne|lt|gt|le|ge)$/.test(word))
+	);
 }
 
-const GH_BODY_FLAGS = ["-f", "-F", "--field", "--raw-field", "--input"];
-const GH_READ_VERBS = new Set(["list", "view", "download"]);
-const GH_REPO_CHANGES = new Set([
-	"create",
-	"delete",
-	"edit",
-	"rename",
-	"archive",
-	"unarchive",
-]);
+/** Why a line the lexer could not read is held. */
+const UNREADABLE: Held = {
+	reason: "the command line is too long or too nested to check",
+	class: "shell.unreadable",
+};
 
-/** Why a `gh` command writes to GitHub in a way the owner approves, or undefined. */
-function ghHeld(args: string[]): string | undefined {
-	const [group, verb] = args.filter((a) => !a.startsWith("-"));
-	switch (group) {
-		case "pr":
-			return verb === "merge" ? "merges a pull request" : undefined;
-		case "api": {
-			const body = args.some((a) =>
-				GH_BODY_FLAGS.some((f) => a === f || a.startsWith(`${f}=`)),
-			);
-			if (verb === "graphql")
-				return args.some((a) => /\bmutation\b/.test(a))
-					? "changes GitHub through the API"
-					: undefined;
-			const index = args.findIndex((a) => a === "-X" || a === "--method");
-			const method = (
-				index === -1
-					? args.find((a) => a.startsWith("--method="))?.slice(9)
-					: args[index + 1]
-			)?.toUpperCase();
-			return body || (method !== undefined && method !== "GET")
-				? "changes GitHub through the API"
-				: undefined;
-		}
-		case "release":
-		case "secret":
-		case "variable":
-			return verb && !GH_READ_VERBS.has(verb)
-				? `changes GitHub ${group}s`
-				: undefined;
-		case "repo":
-			return verb && GH_REPO_CHANGES.has(verb)
-				? `changes a GitHub repository (${verb})`
-				: undefined;
-		default:
-			return undefined;
+/**
+ * Why a script another shell runs (`bash -c`) is held. A script with a substitution the outer shell
+ * expands, or one that is a variable, is built from output not known here, so it is held whole. A
+ * substitution the outer shell leaves alone (single quotes) is the inner shell's, and judged as one.
+ */
+function scriptHeld(
+	script: string,
+	state: LineState,
+	policy: PushPolicy,
+): Held[] {
+	if (script.includes(EXPANDED)) return [DYNAMIC_SCRIPT];
+	if (script.trimStart().startsWith("$")) {
+		const known = expandName(script, state);
+		return known === undefined
+			? [DYNAMIC_SCRIPT]
+			: commandHeld(known, state, policy);
 	}
+	return commandHeld(script, state, policy);
 }
 
-/** Why a command line is held; a `bash -c` inside one starts from the outer line's state. */
+const DYNAMIC_SCRIPT: Held = {
+	reason: "a script built at run time",
+	class: "shell.unreadable",
+};
+
+/** Every reason a command line is held, command by command; a `bash -c` inside one starts from the outer line's state. */
 function commandHeld(
 	command: string,
 	outer: LineState,
 	policy: PushPolicy,
-): string | undefined {
+): Held[] {
 	const state: LineState = {
 		...lineState(command, outer.workspace, undefined),
+		written: new Set(outer.written),
+		bound: new Set([
+			...outer.bound,
+			...lineState(command, outer.workspace, undefined).bound,
+		]),
 		roots: outer.roots,
 		vars: new Map(outer.vars),
 		cwd: outer.cwd,
 	};
-	for (const words of simpleCommands(command)) {
-		const reason = heldReason(words, state, policy);
-		if (reason) return reason;
+	const lexed = lexShell(command);
+	// A line the lexer cannot read could run anything.
+	if (lexed.unreadable) return [UNREADABLE];
+	const found: Held[] = [];
+	// Arithmetic evaluates a `$(` in the value of a variable, text this rule cannot follow.
+	if (
+		lexed.literalSubstitution &&
+		(lexed.arithmetic || lexed.commands.some(evaluatesArithmetic))
+	)
+		found.push(DYNAMIC_SCRIPT);
+	let counts: Map<string, number> | undefined;
+	for (const words of lexed.commands) {
+		found.push(...heldReasons(words, state, policy));
+		const [first, ...rest] = program(words);
+		recordWrites(words, first ? teeOperands(first, rest) : [], state);
 		follow(program(words), state);
 		// `export` and `cd` are kept by program(); bare assignments are dropped by it.
-		if (words.every((w) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(w)))
-			follow(words, state);
+		if (words.every((w) => ASSIGNMENT_WORD.test(w))) follow(words, state);
+		counts ??= bindingCounts(command);
+		forgetRebound(words, state, counts);
 	}
-	return undefined;
+	return found;
 }
 
 /**
@@ -406,6 +361,44 @@ export function shellActionNeedingConfirmation(
 	context: HoldContext & { workspace: string },
 	policy: PushPolicy = {},
 ): string | undefined {
+	return shellHold(toolName, input, context, policy)?.action;
+}
+
+/**
+ * What a shell call is held for, in words, and the class of every command it is held for. A
+ * classifier that fails holds the call: no error lets a command run unjudged.
+ */
+function shellHold(
+	toolName: string,
+	input: Record<string, unknown>,
+	context: HoldContext & { workspace: string },
+	policy: PushPolicy,
+): { action: string; classes: ShellClass[] } | undefined {
+	try {
+		return judge(toolName, input, context, policy);
+	} catch {
+		if (!SHELL_TOOLS.includes(toolName as (typeof SHELL_TOOLS)[number]))
+			return undefined;
+		let detail = `the ${toolName} call`;
+		try {
+			if (toolName === "bash" && typeof input.command === "string")
+				detail = `the shell command \`${input.command.slice(0, MAX_SHOWN_COMMAND)}\``;
+		} catch {
+			// The input itself cannot be read; the call is held without showing it.
+		}
+		return {
+			action: `run ${detail} on the host (it could not be checked)`,
+			classes: ["shell.unreadable"],
+		};
+	}
+}
+
+function judge(
+	toolName: string,
+	input: Record<string, unknown>,
+	context: HoldContext & { workspace: string },
+	policy: PushPolicy,
+): { action: string; classes: ShellClass[] } | undefined {
 	const state = lineState(
 		typeof input.command === "string" ? input.command : "",
 		context.workspace,
@@ -413,16 +406,23 @@ export function shellActionNeedingConfirmation(
 	);
 	if (toolName === "bash") {
 		const command = typeof input.command === "string" ? input.command : "";
-		const reason = commandHeld(command, state, policy);
-		return reason
-			? `run the shell command \`${command.slice(0, MAX_SHOWN_COMMAND)}\` on the host (${reason})`
+		const found = commandHeld(command, state, policy);
+		const [first] = found;
+		return first
+			? {
+					action: `run the shell command \`${command.slice(0, MAX_SHOWN_COMMAND)}\` on the host (${first.reason})`,
+					classes: [...new Set(found.map((held) => held.class))],
+				}
 			: undefined;
 	}
 	if (toolName === "write" || toolName === "edit") {
 		const path = typeof input.path === "string" ? input.path : "";
 		return writable(path.replace(/^@/, ""), state)
 			? undefined
-			: `${toolName} the file ${path} on the host`;
+			: {
+					action: `${toolName} the file ${path} on the host`,
+					classes: ["shell.write"],
+				};
 	}
 	return undefined;
 }
@@ -447,6 +447,15 @@ export function shellHoldRuleFor(policy: PushPolicy = {}): Readonly<HoldRule> {
 						{ ...context, workspace: context.workspace },
 						frozen,
 					),
+		holdClasses: (tool, input, context) =>
+			context.workspace === undefined
+				? undefined
+				: shellHold(
+						tool,
+						input,
+						{ ...context, workspace: context.workspace },
+						frozen,
+					)?.classes,
 	});
 }