pi-robot-hand 0.1.1 → 0.2.1

package/src/hand.ts

@@ -1,7 +1,17 @@
 /** What the agent hands over, and how each of the user's choices turns into editor or clipboard text. */
 
 export type Kind = "shell" | "pi";
-export type Choice = "prompt" | "clipboard" | "cancel";
+export type Preferred = "prompt" | "clipboard" | "herdr-type" | "herdr-run";
+export type Choice = Preferred | "cancel";
+
+/** Where the hand-over can go in this session. */
+export interface Reach {
+	hasDraft: boolean;
+	/** The local terminal UI, where the clipboard works. */
+	canCopy: boolean;
+	/** pi runs inside a Herdr pane, so a sibling pane can be opened. */
+	inHerdr: boolean;
+}
 
 export interface Offer {
 	command: string;
@@ -32,15 +42,30 @@ export function promptText(offer: Offer): string {
 	return offer.kind === "shell" ? `! ${offer.command}` : offer.command;
 }
 
+// When the preferred choice is unavailable, the next one in its chain leads instead.
+const FALLBACK: Record<Preferred, Preferred[]> = {
+	prompt: ["prompt"],
+	clipboard: ["clipboard", "prompt"],
+	"herdr-type": ["herdr-type", "clipboard", "prompt"],
+	"herdr-run": ["herdr-run", "herdr-type", "clipboard", "prompt"],
+};
+
 /**
- * The choices shown to the user. The clipboard needs the local terminal and only makes sense for a
- * shell command run elsewhere; a pi command only runs inside pi.
+ * The choices shown to the user, the preferred one first so the cursor starts on it. The clipboard
+ * needs the local terminal and Herdr panes need pi inside Herdr; both only make sense for a shell
+ * command, since a pi command only runs inside pi.
  */
-export function options(offer: Offer, hasDraft: boolean, canCopy: boolean): Option[] {
-	const list: Option[] = [{ choice: "prompt", label: hasDraft ? "Put it in my prompt (replaces my draft)" : "Put it in my prompt" }];
-	if (canCopy && offer.kind === "shell") list.push({ choice: "clipboard", label: "Copy it to the clipboard" });
-	list.push({ choice: "cancel", label: "No, thanks" });
-	return list;
+export function options(offer: Offer, reach: Reach, preferred: Preferred = "prompt"): Option[] {
+	const shell = offer.kind === "shell";
+	const list: Option[] = [{ choice: "prompt", label: reach.hasDraft ? "Put it in my prompt (replaces my draft)" : "Put it in my prompt" }];
+	if (shell && reach.canCopy) list.push({ choice: "clipboard", label: "Copy it to the clipboard" });
+	if (shell && reach.inHerdr) {
+		list.push({ choice: "herdr-type", label: "Type it into a new Herdr pane (I press Enter)" });
+		list.push({ choice: "herdr-run", label: "Run it in a new Herdr pane" });
+	}
+	const lead = FALLBACK[preferred].find((choice) => list.some((option) => option.choice === choice)) ?? "prompt";
+	const ordered = [...list.filter((option) => option.choice === lead), ...list.filter((option) => option.choice !== lead)];
+	return [...ordered, { choice: "cancel", label: "No, thanks" }];
 }
 
 /** The selector title: why the agent hands this over, then exactly what the user would run. */
@@ -51,11 +76,15 @@ export function dialogTitle(offer: Offer, reason: string): string {
 /** What the tool tells the agent after the user chose. */
 export function resultText(choice: Choice, offer: Offer): string {
 	if (choice === "prompt") {
-		const output = offer.kind === "shell" ? " Its output appears in the conversation when they run it." : "";
+		const output = offer.kind === "shell" ? " When they run it, its output returns to the conversation and starts your next turn." : "";
 		return `The user put \`${promptText(offer)}\` in their prompt; it runs only when they press Enter.${output} Nothing has run yet; wait for the user.`;
 	}
 	if (choice === "clipboard") {
 		return "The user copied the command to their clipboard to run it themselves. Nothing has run yet; wait for the user to report the result.";
 	}
+	if (choice === "herdr-type" || choice === "herdr-run") {
+		const state = choice === "herdr-run" ? "It is running there" : "It runs when the user presses Enter there";
+		return `The command is in a new Herdr pane. ${state}; when it finishes, the pane closes and its output arrives as a new message. Wait for that message.`;
+	}
 	return "The user declined; nothing was placed or run. Ask how they want to proceed.";
 }

package/src/herdr.ts

@@ -0,0 +1,159 @@
+/**
+ * Herdr hand-over: open a pane below pi, run a small wrapper script there that shows the command
+ * (editable before Enter, or started at once), and record its exit code. A watcher then reads the
+ * command's output from the pane, closes the pane, and reports back. The command keeps the pane's
+ * real terminal, so password prompts and full-screen programs work.
+ */
+
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+import { shellQuote } from "../lib/shell.ts";
+
+export type Exec = (args: string[]) => Promise<{ stdout: string; code: number }>;
+
+export interface HerdrRun {
+	token: string;
+	dir: string;
+	paneId: string;
+	command: string;
+}
+
+export type Outcome =
+	| { kind: "finished"; ran: string; exitCode: number; output: string }
+	| { kind: "cancelled" }
+	| { kind: "closed" };
+
+export const MAX_OUTPUT_LINES = 200;
+export const MAX_OUTPUT_CHARS = 16_000;
+
+export const startMarker = (token: string) => `── robot-hand ${token} ──`;
+export const endMarker = (token: string) => `── robot-hand ${token} done ──`;
+
+/** zsh when installed (its vared edits a prefilled line), otherwise bash 4+ (read -e -i). */
+export function findShell(path = process.env.PATH ?? ""): "zsh" | "bash" {
+	const has = (name: string) => path.split(delimiter).some((dir) => dir && existsSync(join(dir, name)));
+	return has("zsh") ? "zsh" : "bash";
+}
+
+/**
+ * The wrapper the pane runs. Ctrl+C while the line is shown cancels; during the command it stops
+ * the command as usual and the script records 130. The script writes the status file last, via a
+ * rename, so the watcher never reads it half-written.
+ */
+export function wrapperScript(shell: "zsh" | "bash", dir: string, token: string, type: boolean): string {
+	const q = (name: string) => shellQuote(join(dir, name));
+	const done = (value: string) => `printf '%s\\n' ${value} > ${q("status.tmp")} && mv ${q("status.tmp")} ${q("status")}`;
+	const edit = shell === "zsh" ? `vared -p '$ ' cmd` : `read -r -e -i "$cmd" -p '$ ' cmd`;
+	return [
+		`cmd=$(cat ${q("command")})`,
+		`trap '${done("cancelled").replace(/'/g, `'\\''`)}; exit 130' INT`,
+		...(type ? [edit] : []),
+		`printf '%s\\n' "$cmd" > ${q("ran")}`,
+		`trap : INT`,
+		`printf '%s\\n' ${shellQuote(startMarker(token))}`,
+		// A subshell, so an `exit` in the command ends only the command.
+		`(eval "$cmd")`,
+		`code=$?`,
+		`printf '%s\\n' ${shellQuote(endMarker(token))}`,
+		done(`"$code"`),
+		"",
+	].join("\n");
+}
+
+/** The command's output between the run's markers, trimmed to what the model needs. */
+export function sliceOutput(screen: string, token: string): string {
+	const lines = screen.split("\n");
+	const start = lines.findLastIndex((line) => line.trim() === startMarker(token));
+	const end = lines.findLastIndex((line) => line.trim() === endMarker(token));
+	let body = start === -1 ? lines : lines.slice(start + 1, end > start ? end : undefined);
+	while (body.length > 0 && body[body.length - 1]?.trim() === "") body = body.slice(0, -1);
+	let text = body.slice(-MAX_OUTPUT_LINES).join("\n");
+	if (text.length > MAX_OUTPUT_CHARS) text = text.slice(-MAX_OUTPUT_CHARS);
+	const cut = body.length > MAX_OUTPUT_LINES || body.join("\n").length > MAX_OUTPUT_CHARS;
+	return cut ? `[earlier output omitted]\n${text}` : text;
+}
+
+/** Opens the pane below pi, focuses it, and starts the wrapper. */
+export async function startRun(exec: Exec, opts: { piPane: string; cwd: string; tmp: string; command: string; type: boolean; shell: "zsh" | "bash" }): Promise<HerdrRun> {
+	const token = randomBytes(4).toString("hex");
+	const dir = join(opts.tmp, "pi-robot-hand", token);
+	await mkdir(dir, { recursive: true, mode: 0o700 });
+	await writeFile(join(dir, "command"), opts.command, { mode: 0o600 });
+	const script = join(dir, `run.${opts.shell}`);
+	await writeFile(script, wrapperScript(opts.shell, dir, token, opts.type), { mode: 0o600 });
+	await chmod(dir, 0o700);
+
+	const split = await exec(["pane", "split", "--pane", opts.piPane, "--direction", "down", "--ratio", "0.4", "--cwd", opts.cwd]);
+	const paneId = parsePaneId(split.stdout);
+	if (split.code !== 0 || !paneId) {
+		await rm(dir, { recursive: true, force: true });
+		throw new Error(`herdr could not open a pane: ${split.stdout.trim() || `exit ${split.code}`}`);
+	}
+	await exec(["pane", "focus", "--pane", opts.piPane, "--direction", "down"]);
+	const run = await exec(["pane", "run", paneId, `${opts.shell} ${shellQuote(script)}`]);
+	if (run.code !== 0) {
+		await exec(["pane", "close", paneId]);
+		await rm(dir, { recursive: true, force: true });
+		throw new Error(`herdr could not start the command in pane ${paneId}: exit ${run.code}`);
+	}
+	return { token, dir, paneId, command: opts.command };
+}
+
+function parsePaneId(stdout: string): string | undefined {
+	try {
+		const parsed = JSON.parse(stdout) as { result?: { pane?: { pane_id?: unknown } } };
+		const id = parsed.result?.pane?.pane_id;
+		return typeof id === "string" ? id : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * One watcher step: undefined while the command is still going, otherwise the outcome. A finished
+ * run has its output read and its pane closed; a pane the user closed first reports `closed`.
+ */
+export async function checkRun(exec: Exec, run: HerdrRun, checkPane: boolean): Promise<Outcome | undefined> {
+	const status = await readFile(join(run.dir, "status"), "utf8").catch(() => undefined);
+	if (status === undefined) {
+		if (!checkPane) return undefined;
+		const pane = await exec(["pane", "get", run.paneId]);
+		return pane.code === 0 ? undefined : { kind: "closed" };
+	}
+	const value = status.trim();
+	if (value === "cancelled") {
+		await exec(["pane", "close", run.paneId]);
+		return { kind: "cancelled" };
+	}
+	const ran = (await readFile(join(run.dir, "ran"), "utf8").catch(() => run.command)).trim();
+	const screen = await exec(["pane", "read", run.paneId, "--source", "recent-unwrapped", "--lines", "2000"]);
+	await exec(["pane", "close", run.paneId]);
+	return { kind: "finished", ran, exitCode: Number(value), output: screen.code === 0 ? sliceOutput(screen.stdout, run.token) : "[output unavailable]" };
+}
+
+export async function cleanup(run: HerdrRun): Promise<void> {
+	await rm(run.dir, { recursive: true, force: true });
+}
+
+/** The message that brings the agent back once the pane is done. */
+export function outcomeText(outcome: Outcome, command: string): string {
+	if (outcome.kind === "cancelled") {
+		return `The user cancelled \`${command}\` in the Herdr pane before running it; nothing ran. Ask how they want to proceed.`;
+	}
+	if (outcome.kind === "closed") {
+		return `The Herdr pane for \`${command}\` closed before the command finished; whether it ran is unknown. Ask the user.`;
+	}
+	const edited = outcome.ran === command ? "" : ` (edited from \`${command}\`)`;
+	return [
+		`The user ran this in a Herdr pane${edited}, which is now closed. Exit code ${outcome.exitCode}.`,
+		"",
+		"```",
+		`$ ${outcome.ran}`,
+		outcome.output,
+		"```",
+		"",
+		"Read the output and respond to it.",
+	].join("\n");
+}

package/src/index.ts

@@ -1,20 +1,28 @@
 /**
  * pi-robot-hand: the agent hands the user a command. After the user agrees, it lands in the pi
- * prompt (shell commands as `! command`) or the clipboard. The user decides whether to run it;
- * the agent never does.
+ * prompt (shell commands as `! command`), the clipboard, or a new Herdr pane. The user decides
+ * whether to run it; the agent never does. A Herdr pane closes when its command finishes and the
+ * output comes back as a message that starts the agent's next turn.
  */
 
+import { tmpdir } from "node:os";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { copyToClipboard, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { type Choice, dialogTitle, options, promptText, resultText, toOffer } from "./hand.ts";
+import { checkRun, cleanup, type Exec, findShell, type HerdrRun, outcomeText, startRun } from "./herdr.ts";
 
 interface HandDetails {
 	command: string;
 	status: "waiting" | Choice;
 }
 
+export const HERDR_RESULT_TYPE = "robot-hand-herdr";
+export const WATCH_MS = 500;
+// Every this many watch ticks, also check that the pane still exists.
+const PANE_CHECK_EVERY = 6;
+
 const Params = Type.Object({
 	command: Type.String({
 		description: "The command to hand over. kind=shell: a shell command without a leading `!`. kind=pi: a pi slash command such as `/reload`.",
@@ -23,23 +31,74 @@ const Params = Type.Object({
 	kind: Type.Optional(
 		StringEnum(["shell", "pi"] as const, {
 			description:
-				"shell: goes to the prompt as `! command` (output returns to the conversation) or to the clipboard for another terminal. pi: a pi slash command, placed in the prompt as-is. Default shell.",
+				"shell: goes to the prompt as `! command` (output returns to the conversation), the clipboard, or a new Herdr pane. pi: a pi slash command, placed in the prompt as-is. Default shell.",
+		}),
+	),
+	default: Type.Optional(
+		StringEnum(["prompt", "clipboard", "herdr-type", "herdr-run"] as const, {
+			description:
+				"The option the selector starts on. prompt (default): pi's `!`, which has no terminal for input. For interactive commands (password or sudo prompts, confirmations, ssh, full-screen programs) use herdr-type, which opens a real terminal pane; outside Herdr it falls back to clipboard, then prompt. herdr-run starts the command in the pane at once.",
 		}),
 	),
 });
 
-export function createRobotHand(copy: (text: string) => Promise<void> = copyToClipboard) {
+export function createRobotHand(copy: (text: string) => Promise<void> = copyToClipboard, env: NodeJS.ProcessEnv = process.env, tmp: string = tmpdir()) {
 	return function robotHand(pi: ExtensionAPI) {
+		const exec: Exec = async (args) => {
+			const result = await pi.exec(env.HERDR_BIN_PATH || "herdr", args);
+			return { stdout: result.stdout, code: result.code };
+		};
+		const runs = new Map<string, { run: HerdrRun; ticks: number; busy: boolean }>();
+		let timer: ReturnType<typeof setInterval> | undefined;
+
+		const watch = (): void => {
+			for (const entry of runs.values()) {
+				if (entry.busy) continue;
+				entry.busy = true;
+				entry.ticks++;
+				const report = (content: string): void => {
+					pi.sendMessage({ customType: HERDR_RESULT_TYPE, content, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+				};
+				checkRun(exec, entry.run, entry.ticks % PANE_CHECK_EVERY === 0)
+					.then(async (outcome) => {
+						if (!outcome) return;
+						runs.delete(entry.run.token);
+						await cleanup(entry.run);
+						report(outcomeText(outcome, entry.run.command));
+					})
+					.catch((error: unknown) => {
+						runs.delete(entry.run.token);
+						report(
+							`robot_hand lost track of the Herdr pane ${entry.run.paneId} running \`${entry.run.command}\`: ${(error as Error).message}. Its result is unknown; ask the user.`,
+						);
+					})
+					.finally(() => {
+						entry.busy = false;
+						if (runs.size === 0 && timer) {
+							clearInterval(timer);
+							timer = undefined;
+						}
+					});
+			}
+		};
+
+		pi.on("session_shutdown", () => {
+			if (timer) clearInterval(timer);
+			timer = undefined;
+			runs.clear();
+		});
+
 		pi.registerTool({
 			name: "robot_hand",
 			label: "Robot Hand",
 			description:
-				"Hand the user a command to run themselves. The user sees the command and the reason, then puts it in their pi prompt (a shell command becomes `! command`, whose output returns to the conversation when they press Enter), copies it to the clipboard, or declines. The tool returns the user's choice; it never runs the command.",
-			promptSnippet: "Hand the user a command to run themselves, via their pi prompt or clipboard",
+				"Hand the user a command to run themselves. The user sees the command and the reason, then puts it in their pi prompt (a shell command becomes `! command`, whose output returns to the conversation when they press Enter), copies it to the clipboard, sends it to a new Herdr pane (closed when it finishes, its output returning as a message), or declines. The tool returns the user's choice; it never runs the command.",
+			promptSnippet: "Hand the user a command to run themselves, via their pi prompt, clipboard, or a Herdr pane",
 			promptGuidelines: [
 				"Use robot_hand when the user has to run a command themselves: pi slash commands such as /reload, interactive or sudo commands, commands a guard blocked, or anything they asked to run on their own.",
 				"Pass one command per robot_hand call and write the reason in the user's language.",
-				"After robot_hand places or copies a command, nothing has run yet: wait for the user instead of assuming the result.",
+				"Set robot_hand `default` to herdr-type for a command that needs terminal input (password, sudo, confirmation, ssh, a full-screen program); pi's `!` gives it no terminal.",
+				"After robot_hand places, copies, or sends a command, nothing has run yet: wait for the user or the result message instead of assuming the result.",
 			],
 			parameters: Params,
 			executionMode: "sequential",
@@ -50,7 +109,13 @@ export function createRobotHand(copy: (text: string) => Promise<void> = copyToCl
 				}
 				const offer = toOffer(params.command, params.kind);
 				const text = promptText(offer);
-				const choices = options(offer, ctx.ui.getEditorText().trim().length > 0, ctx.mode === "tui");
+				const piPane = env.HERDR_PANE_ID;
+				const reach = {
+					hasDraft: ctx.ui.getEditorText().trim().length > 0,
+					canCopy: ctx.mode === "tui",
+					inHerdr: ctx.mode === "tui" && Boolean(piPane),
+				};
+				const choices = options(offer, reach, params.default);
 
 				onUpdate?.({ content: [{ type: "text", text: "Waiting for the user to take the command..." }], details: { command: text, status: "waiting" } });
 				pi.events.emit("herdr:blocked", { active: true, label: "Waiting for the user to take a command" });
@@ -72,6 +137,10 @@ export function createRobotHand(copy: (text: string) => Promise<void> = copyToCl
 				} else if (choice === "clipboard") {
 					await copy(offer.command);
 					ctx.ui.notify("Command copied to the clipboard.", "info");
+				} else if ((choice === "herdr-type" || choice === "herdr-run") && piPane) {
+					const run = await startRun(exec, { piPane, cwd: ctx.cwd, tmp, command: offer.command, type: choice === "herdr-type", shell: findShell(env.PATH) });
+					runs.set(run.token, { run, ticks: 0, busy: false });
+					timer ??= setInterval(watch, WATCH_MS);
 				}
 				return {
 					content: [{ type: "text", text: resultText(choice, offer) }],
@@ -97,6 +166,8 @@ export function createRobotHand(copy: (text: string) => Promise<void> = copyToCl
 				if (details.status === "waiting") return new Text(theme.fg("dim", "Waiting for you to take the command"), 0, 0);
 				if (details.status === "prompt") return new Text(`${theme.fg("success", "✓ ")}In your prompt — press Enter to run it`, 0, 0);
 				if (details.status === "clipboard") return new Text(`${theme.fg("success", "✓ ")}Copied to your clipboard`, 0, 0);
+				if (details.status === "herdr-type") return new Text(`${theme.fg("success", "✓ ")}In a new Herdr pane — press Enter there to run it`, 0, 0);
+				if (details.status === "herdr-run") return new Text(`${theme.fg("success", "✓ ")}Running in a new Herdr pane`, 0, 0);
 				return new Text(theme.fg("warning", "Declined — nothing placed or run"), 0, 0);
 			},
 		});

package/src/secret-drop/guard.ts

@@ -0,0 +1,204 @@
+/**
+ * Decide whether a tool call would expose or clobber a protected secret file.
+ */
+
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, resolve } from "node:path";
+
+/** Commands that print, copy, or open file contents. Scripts that consume a file stay allowed. */
+const READERS = new Set([
+	"cat", "bat", "less", "more", "most", "head", "tail", "tac", "nl", "pr",
+	"grep", "egrep", "fgrep", "rg", "ag", "ack", "sed", "awk", "gawk", "cut", "sort", "uniq", "paste", "column",
+	"strings", "xxd", "hexdump", "od", "base64", "base32", "diff", "cmp", "comm",
+	"vi", "vim", "nvim", "nano", "emacs", "code", "open", "pbcopy", "xclip", "xsel",
+	"cp", "mv", "scp", "rsync", "tee", "dd", "install", "jq", "yq", "dotenv", "envsubst",
+]);
+
+/** Prefixes that run the next word as the command. */
+const WRAPPERS = new Set(["sudo", "doas", "env", "command", "builtin", "exec", "time", "nice", "nohup", "xargs", "stdbuf", "timeout"]);
+/** Shells whose `-c` argument is itself a command line. */
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+const MAX_NESTING = 4;
+
+const FILE_TOOLS = new Set(["read", "edit", "write", "grep"]);
+
+export function expandHome(path: string): string {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/")) return resolve(homedir(), path.slice(2));
+	return path;
+}
+
+/** Absolute path with symlinks resolved when the file exists. */
+export function canonicalPath(path: string, cwd: string): string {
+	const expanded = expandHome(path.startsWith("@") ? path.slice(1) : path);
+	const absolute = isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+	try {
+		return realpathSync(absolute);
+	} catch {
+		return absolute;
+	}
+}
+
+function blockReason(path: string): string {
+	return [
+		`${path} holds a secret managed by secret_drop; its contents stay out of the conversation.`,
+		"Let the program that needs it read the file itself, or ask the user to run the consuming command with `!`.",
+		"Call secret_drop again to change the value.",
+	].join(" ");
+}
+
+/**
+ * Split a command line into simple commands at `;`, `|`, `&`, newlines, and parentheses outside quotes,
+ * and at every command substitution (`$(` or a backtick) outside single quotes.
+ */
+function splitSegments(command: string): string[] {
+	const segments: string[] = [];
+	let current = "";
+	let quote: "'" | '"' | undefined;
+	const flush = () => {
+		if (current.trim()) segments.push(current);
+		current = "";
+	};
+	for (let i = 0; i < command.length; i++) {
+		const ch = command[i] ?? "";
+		if (quote === "'") {
+			if (ch === "'") quote = undefined;
+			current += ch;
+		} else if (ch === "\\") {
+			current += ch + (command[i + 1] ?? "");
+			i += 1;
+		} else if (ch === "`" || (ch === "$" && command[i + 1] === "(")) {
+			flush();
+			quote = undefined;
+			if (ch === "$") i += 1;
+		} else if (quote === '"') {
+			if (ch === '"') quote = undefined;
+			current += ch;
+		} else if (ch === "'" || ch === '"') {
+			quote = ch;
+			current += ch;
+		} else if (";|&\n()".includes(ch)) {
+			flush();
+		} else {
+			current += ch;
+		}
+	}
+	flush();
+	return segments;
+}
+
+/** Shell words of one simple command, quotes removed. Redirection operators are separate words. */
+function shellWords(segment: string): string[] {
+	const words: string[] = [];
+	let word = "";
+	let started = false;
+	let quote: "'" | '"' | undefined;
+	const push = () => {
+		if (started) words.push(word);
+		word = "";
+		started = false;
+	};
+	for (let i = 0; i < segment.length; i++) {
+		const ch = segment[i] ?? "";
+		if (quote) {
+			if (ch === quote) quote = undefined;
+			else if (quote === '"' && ch === "\\" && i + 1 < segment.length) word += segment[++i];
+			else word += ch;
+		} else if (ch === "'" || ch === '"') {
+			quote = ch;
+			started = true;
+		} else if (ch === "\\") {
+			word += segment[++i] ?? "";
+			started = true;
+		} else if (/\s/.test(ch)) {
+			push();
+		} else if (ch === "<" || ch === ">") {
+			push();
+			let op = ch;
+			while (segment[i + 1] === "<" || segment[i + 1] === ">") op += segment[++i];
+			words.push(op);
+		} else {
+			word += ch;
+			started = true;
+		}
+	}
+	push();
+	return words;
+}
+
+/** Return the protected path a command line reads or redirects, otherwise undefined. */
+function findBashHit(command: string, cwd: string, isProtected: (canonical: string) => boolean, depth: number): string | undefined {
+	if (depth > MAX_NESTING) return undefined;
+	const hits = (word: string) => word.length > 0 && isProtected(canonicalPath(word, cwd));
+	for (const segment of splitSegments(command.replace(/\$\{?HOME\}?/g, homedir()))) {
+		const tokens = shellWords(segment);
+		const args: string[] = [];
+		for (let i = 0; i < tokens.length; i++) {
+			const token = tokens[i] ?? "";
+			if (!/^[<>]+$/.test(token)) {
+				args.push(token);
+				continue;
+			}
+			const target = tokens[++i] ?? "";
+			// `<<` and `<<<` take a heredoc delimiter or a literal string, not a file.
+			if (!token.startsWith("<<") && hits(target)) return target;
+		}
+
+		let k = 0;
+		let wrapped = false;
+		while (k < args.length) {
+			const word = args[k] ?? "";
+			if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) k += 1;
+			else if (WRAPPERS.has(basename(word))) {
+				wrapped = true;
+				k += 1;
+			} else if (wrapped && (word.startsWith("-") || /^\d/.test(word))) k += 1;
+			else break;
+		}
+		const name = basename(args[k] ?? "");
+		const rest = args.slice(k + 1);
+
+		if (SHELLS.has(name)) {
+			const flag = rest.findIndex((word) => /^-[a-z]*c[a-z]*$/.test(word));
+			const script = flag === -1 ? undefined : rest[flag + 1];
+			const hit = script ? findBashHit(script, cwd, isProtected, depth + 1) : undefined;
+			if (hit) return hit;
+		} else if (name === "eval") {
+			const hit = findBashHit(rest.join(" "), cwd, isProtected, depth + 1);
+			if (hit) return hit;
+		} else if (READERS.has(name)) {
+			const hit = rest.find((word) => hits(word) || (word.includes("=") && hits(word.slice(word.indexOf("=") + 1))));
+			if (hit) return hit;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Return a block reason when the call touches a protected path, otherwise undefined.
+ * `isProtected` receives canonical absolute paths.
+ */
+export function checkToolCall(
+	toolName: string,
+	input: Record<string, unknown>,
+	cwd: string,
+	isProtected: (canonical: string) => boolean,
+): string | undefined {
+
+	if (FILE_TOOLS.has(toolName)) {
+		const path = input.path;
+		if (typeof path !== "string" || path.length === 0) return undefined;
+		const target = canonicalPath(path, cwd);
+		return isProtected(target) ? blockReason(path) : undefined;
+	}
+
+	if (toolName === "bash") {
+		const command = input.command;
+		if (typeof command !== "string") return undefined;
+		const hit = findBashHit(command, cwd, isProtected, 0);
+		return hit ? blockReason(hit) : undefined;
+	}
+
+	return undefined;
+}