@openlines/opl-pi-sht 0.2.6 → 0.2.8

package/extensions/opl-guardian/README.md

@@ -1,51 +1,49 @@
 # opl-guardian
 
-Prevents malformed assistant tool calls from entering Pi session history. It runs on every provider and model through Pi's `message_end` hook, removes protocol-invalid calls before Pi persists or replays them, and records each removal as JSON Lines evidence.
+A configurable session and tool safety extension. `opl-guardian` filters malformed assistant tool calls, prompts before dangerous Bash commands, blocks operations on protected paths, and confirms destructive session transitions. It replaces the standalone `permission-gate`, `protected-paths`, and `confirm-destructive` extensions while retaining malformed-call diagnostics. It adds no tools, commands, prompts, or model-facing schema overhead.
 
->
-> This is the first feature that opl-guardian can do for now. If I happen to encounter another error/issue that can be (possibly) fixed via extensions, I might add that up in this extension.
->
+## Configuration
 
-## Commands, tools, and configuration
+Copy `configs/opl-guardian.json.sample` to `~/.pi/agent/configs/opl-guardian.json` and customize it. For a package install, find the sample under the installed package's `configs/` directory. All settings are optional; absent settings use the defaults from the sample.
 
-No commands, tools, or configuration. Loading the extension is the entire interface and adds no prompt or tool-schema overhead.
+- `permissionGate.patterns` is a list of case-insensitive JavaScript regex strings. A match prompts for confirmation in the terminal or over RPC; Yes allows the command, while No or cancel blocks it. The prompt defaults to No (fail closed), so an accidental or unattended confirmation denies rather than approves. An empty list disables pattern matching. `permissionGate.blockWithoutUI` defaults to `true` and blocks a match when confirmation UI is unavailable. Configured patterns replace the defaults; update existing config files manually to adopt changes to default patterns.
+- `protectedPaths.paths` contains `{ "path", "deny" }` entries. Valid denied operations are `read`, `write`, `edit`, and `bash`. Bare names match exact path segments for file tools; Bash uses literal command matching. Absolute and `~/` entries match resolved paths and descendants for file tools. An empty list disables path rules.
+- `confirmDestructive` controls confirmations for starting a new session (`clearSession`), resuming another session when unanswered user work exists (`switchWithUnsavedWork`), and forking (`forkSession`). All default to `true`. `confirmDestructive.blockWithoutUI` also defaults to `true`; set it to `false` to allow these actions without an interactive confirmation.
+- `dropMalformedToolCalls` defaults to `true`. Set it to `false` to disable only malformed-call filtering and its incident log.
 
-## What it guards
+Malformed or invalid config sections generate a warning when a UI is available and fall back to safe defaults for the affected settings. Invalid individual regexes or protected-path entries are reported; valid entries continue to apply. Empty arrays are explicit opt-outs.
 
-A tool call is malformed when its `id` or `name` is blank after trimming whitespace. Such a record cannot be safely replayed through OpenAI-compatible tool-call APIs: a later provider request may reject it and block the session until its history is abandoned.
+If migrating from the standalone extensions, manually move their settings into the corresponding `permissionGate` and `protectedPaths` sections. `opl-guardian` does not read or merge legacy config files. Credits to pi's sample extensions [here](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions).
 
-`opl-guardian` does not reject an unfamiliar but non-empty tool name. That is a normal model/tool-resolution error, not an invalid protocol envelope.
+## What it guards
 
-| Assistant response | Guardian behavior |
-| --- | --- |
-| No malformed calls | Leaves the response unchanged. |
-| Valid and malformed calls | Drops only malformed calls, preserves valid calls and `toolUse`, appends a diagnostic, and lets Pi execute the valid calls normally. |
-| Only malformed calls | Removes every call, returns a text-only `stop` response, and tells the user to send another prompt. |
+### Dangerous Bash commands
 
-When a UI is available, every incident also produces a warning notification.
+The default patterns cover recursive `rm` flags (including `-rf`, `-fr`, and separate `-f -r`), `sudo`, `chmod`/`chown` to mode `777`, `printenv`, and bare `env`. Matching commands require confirmation. Without a confirmation UI they are blocked by default.
 
-## Forensic JSONL
+### Protected paths
 
-Each incident appends one JSON object to:
+Defaults protect `.env` from read/write/edit/Bash, `.git/` from read/write/edit, `node_modules/` from write/edit, and `~/.pi/agent/auth.json` from read/write/edit/Bash. File-tool path checks compare both the supplied path and its filesystem-resolved target, including existing symlinks and symlinked parents for new files; paths that cannot be safely resolved are blocked when an applicable path rule is active. A path denial is a hard block and takes precedence over a dangerous-command confirmation for the same Bash call. These are preflight checks, not filesystem confinement: paths can change between the check and the tool operation. Bash matching is literal and cannot reliably detect indirect access through scripts, variables, or shell expansion (for example `cat "$HOME/.pi/agent/auth.json"` misses the auth file); it also over-blocks commands that merely *mention* a protected path or name (for example `grep .env notes.md`). Do not rely on guardian alone as a security boundary against untrusted shell commands.
 
-```text
-<project cwd>/err/guardian.jsonl
-```
+### Destructive session actions
+
+Starting a new session, resuming another session with a pending user message, and forking prompt for confirmation by default. Configured actions are canceled if no UI is available unless `confirmDestructive.blockWithoutUI` is explicitly set to `false`.
 
-A record includes timestamp, session ID, project CWD, provider, model, response ID when available, and the removed `toolCall` blocks. It does not log prompts, assistant text, thinking, or tool results.
+### Malformed provider tool calls
 
-Tool-call arguments can still contain project paths, commands, or user text. Add `err/` to the project’s version-control ignore policy if it is not already ignored, and treat the file as local diagnostic data.
+A tool call is malformed when its ID or name is blank after trimming whitespace. The extension drops malformed calls before Pi persists or replays them, preserves valid sibling calls, and turns invalid-only responses into a text-only stop so the user can continue. Unfamiliar but non-empty tool names are not rejected. As defense in depth, the `tool_call` boundary also blocks any blank-id/name call that slips through, so a malformed call can never execute even if the `message_end` filter is bypassed.
 
-If the log write fails, guardian still removes the malformed calls. The session diagnostic and UI warning report that the forensic file could not be written rather than claiming it was saved.
+## Forensic JSONL
 
-## Architecture
+Each malformed-call incident appends one JSON object to:
 
 ```text
-guardian.ts  Pure malformed-call filter and JSONL incident-record builder.
-index.ts     Pi message_end handler, project-local JSONL append, UI notification.
+<project cwd>/err/guardian.jsonl
 ```
 
-The extension has no runtime dependencies. Run its checks with:
+Records include timestamp (falling back to the current time when a provider omitted or zeroed it), session/project/provider/model metadata, and removed tool-call blocks. The log does not contain prompts, assistant text, thinking, or tool results, but tool-call arguments may include paths, commands, or user text. Treat it as local diagnostic data and ignore `err/` in version control where appropriate. On POSIX, a newly created log is restricted to mode `0600` on a best-effort basis. If logging fails, malformed calls are still removed and the diagnostic reports the write failure.
+
+## Testing
 
 ```bash
 npm run test:opl-guardian

package/extensions/opl-guardian/config.ts

@@ -0,0 +1,199 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type Op = "read" | "write" | "edit" | "bash";
+
+export interface PathEntry {
+  path: string;
+  deny: Op[];
+}
+
+export interface GuardianConfig {
+  permissionGate: {
+    patterns: RegExp[];
+    blockWithoutUI: boolean;
+  };
+  protectedPaths: {
+    paths: PathEntry[];
+  };
+  confirmDestructive: {
+    clearSession: boolean;
+    switchWithUnsavedWork: boolean;
+    forkSession: boolean;
+    blockWithoutUI: boolean;
+  };
+  dropMalformedToolCalls: boolean;
+}
+
+const DEFAULT_PATTERN_STRINGS = [
+  "\\brm\\s+(?:(?:-[a-z]+|--[a-z-]+)\\s+)*(?:-[a-z]*r[a-z]*|--recursive)(?=\\s|$)",
+  "\\bsudo\\b",
+  "\\b(chmod|chown)\\s+(?:-[a-z]+\\s+)*777(?:\\b|$)",
+  "\\bprintenv\\b",
+  "(^|\\s)env(\\s|$)",
+];
+
+const DEFAULT_PATHS: PathEntry[] = [
+  { path: ".env", deny: ["read", "write", "edit", "bash"] },
+  { path: ".git/", deny: ["read", "write", "edit"] },
+  { path: "node_modules/", deny: ["write", "edit"] },
+  { path: "~/.pi/agent/auth.json", deny: ["read", "write", "edit", "bash"] },
+];
+
+export const DEFAULT_CONFIG: GuardianConfig = {
+  permissionGate: {
+    patterns: DEFAULT_PATTERN_STRINGS.map((pattern) => new RegExp(pattern, "i")),
+    blockWithoutUI: true,
+  },
+  protectedPaths: { paths: DEFAULT_PATHS },
+  confirmDestructive: {
+    clearSession: true,
+    switchWithUnsavedWork: true,
+    forkSession: true,
+    blockWithoutUI: true,
+  },
+  dropMalformedToolCalls: true,
+};
+
+const CONFIG_PATH = join(homedir(), ".pi", "agent", "configs", "opl-guardian.json");
+const OPS = new Set<Op>(["read", "write", "edit", "bash"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function cloneDefaults(): GuardianConfig {
+  return {
+    permissionGate: {
+      patterns: DEFAULT_PATTERN_STRINGS.map((pattern) => new RegExp(pattern, "i")),
+      blockWithoutUI: true,
+    },
+    protectedPaths: { paths: DEFAULT_PATHS.map((entry) => ({ ...entry, deny: [...entry.deny] })) },
+    confirmDestructive: { ...DEFAULT_CONFIG.confirmDestructive },
+    dropMalformedToolCalls: true,
+  };
+}
+
+export function parseGuardianConfig(value: unknown): { config: GuardianConfig; warnings: string[] } {
+  const config = cloneDefaults();
+  const warnings: string[] = [];
+
+  if (value === undefined) return { config, warnings };
+  if (!isRecord(value)) {
+    return { config, warnings: ["Invalid opl-guardian config: expected a JSON object; using defaults."] };
+  }
+
+  if (value.permissionGate !== undefined) {
+    if (!isRecord(value.permissionGate)) {
+      warnings.push("Invalid permissionGate section; using defaults.");
+    } else {
+      const section = value.permissionGate;
+      if (section.patterns !== undefined) {
+        if (!Array.isArray(section.patterns)) {
+          warnings.push("permissionGate.patterns must be an array; using defaults.");
+        } else if (section.patterns.length === 0) {
+          config.permissionGate.patterns = [];
+        } else {
+          const patterns: RegExp[] = [];
+          for (const pattern of section.patterns) {
+            if (typeof pattern !== "string") {
+              warnings.push("permissionGate.patterns entries must be strings; ignoring invalid entry.");
+              continue;
+            }
+            try {
+              patterns.push(new RegExp(pattern, "i"));
+            } catch {
+              warnings.push("Invalid permissionGate regex; ignoring it.");
+            }
+          }
+          config.permissionGate.patterns = patterns.length > 0
+            ? patterns
+            : DEFAULT_PATTERN_STRINGS.map((pattern) => new RegExp(pattern, "i"));
+        }
+      }
+      if (section.blockWithoutUI !== undefined) {
+        if (typeof section.blockWithoutUI === "boolean") {
+          config.permissionGate.blockWithoutUI = section.blockWithoutUI;
+        } else {
+          warnings.push("permissionGate.blockWithoutUI must be a boolean; using true.");
+        }
+      }
+    }
+  }
+
+  if (value.protectedPaths !== undefined) {
+    if (!isRecord(value.protectedPaths)) {
+      warnings.push("Invalid protectedPaths section; using defaults.");
+    } else if (value.protectedPaths.paths !== undefined) {
+      const inputPaths = value.protectedPaths.paths;
+      if (!Array.isArray(inputPaths)) {
+        warnings.push("protectedPaths.paths must be an array; using defaults.");
+      } else if (inputPaths.length === 0) {
+        config.protectedPaths.paths = [];
+      } else {
+        const paths: PathEntry[] = [];
+        for (const item of inputPaths) {
+          if (!isRecord(item) || typeof item.path !== "string" || item.path.trim().length === 0 ||
+            !Array.isArray(item.deny) || !item.deny.every((op): op is Op => typeof op === "string" && OPS.has(op as Op))) {
+            warnings.push("Invalid protectedPaths entry; ignoring it.");
+            continue;
+          }
+          paths.push({ path: item.path, deny: item.deny as Op[] });
+        }
+        config.protectedPaths.paths = paths.length > 0
+          ? paths
+          : DEFAULT_PATHS.map((entry) => ({ ...entry, deny: [...entry.deny] }));
+      }
+    }
+  }
+
+  if (value.confirmDestructive !== undefined) {
+    if (!isRecord(value.confirmDestructive)) {
+      warnings.push("Invalid confirmDestructive section; using defaults.");
+    } else {
+      const keys = ["clearSession", "switchWithUnsavedWork", "forkSession", "blockWithoutUI"] as const;
+      for (const key of keys) {
+        const setting = value.confirmDestructive[key];
+        if (setting === undefined) continue;
+        if (typeof setting === "boolean") {
+          config.confirmDestructive[key] = setting;
+        } else {
+          warnings.push(`confirmDestructive.${key} must be a boolean; using true.`);
+        }
+      }
+    }
+  }
+
+  if (value.dropMalformedToolCalls !== undefined) {
+    if (typeof value.dropMalformedToolCalls === "boolean") {
+      config.dropMalformedToolCalls = value.dropMalformedToolCalls;
+    } else {
+      warnings.push("dropMalformedToolCalls must be a boolean; using true.");
+    }
+  }
+
+  return { config, warnings };
+}
+
+export function loadGuardianConfig(): { config: GuardianConfig; warnings: string[] } {
+  let raw: string;
+  try {
+    raw = readFileSync(CONFIG_PATH, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return parseGuardianConfig(undefined);
+    return {
+      config: cloneDefaults(),
+      warnings: [`Could not read ${CONFIG_PATH}; using defaults.`],
+    };
+  }
+
+  try {
+    return parseGuardianConfig(JSON.parse(raw));
+  } catch {
+    return {
+      config: cloneDefaults(),
+      warnings: [`Invalid JSON in ${CONFIG_PATH}; using defaults.`],
+    };
+  }
+}

package/extensions/opl-guardian/guardian.ts

@@ -56,8 +56,12 @@ export function buildIncidentRecord(
   context: IncidentContext,
   removedToolCalls: ToolCall[],
 ): GuardianIncident {
+  // A missing/zero/NaN timestamp yields an invalid Date whose toISOString() throws,
+  // which would silently lose the forensic record. Fall back to the current time.
+  const timestamp =
+    Number.isFinite(message.timestamp) && message.timestamp > 0 ? message.timestamp : Date.now();
   return {
-    timestamp: new Date(message.timestamp).toISOString(),
+    timestamp: new Date(timestamp).toISOString(),
     kind: "malformed_tool_call",
     sessionId: context.sessionId,
     cwd: context.cwd,

package/extensions/opl-guardian/index.ts

@@ -1,13 +1,23 @@
 import type { AssistantMessage } from "@earendil-works/pi-ai";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  isToolCallEventType,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type MessageEndEvent,
+  type SessionBeforeForkEvent,
+  type SessionBeforeSwitchEvent,
+  type ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
 import { appendFile, chmod, mkdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 
+import { loadGuardianConfig, type GuardianConfig } from "./config.js";
 import {
   buildIncidentRecord,
   guardAssistantMessage,
   type GuardianIncident,
 } from "./guardian.js";
+import { getProtectedPathBlock, hasPendingUserWork } from "./policies.js";
 
 const LOG_PATH = join("err", "guardian.jsonl");
 
@@ -38,9 +48,14 @@ function diagnostic(removed: number, logError?: unknown): string {
 }
 
 function appendDiagnostic(message: AssistantMessage, text: string, invalidOnly: boolean): AssistantMessage {
+  // For a mixed response (valid tool calls remain), prepend the notice rather than
+  // appending a trailing text block after toolCall blocks: providers such as Anthropic
+  // require each tool_use to be followed by a tool_result, so a trailing text block does
+  // not round-trip through the wire format. Text-before-tool-calls is the standard
+  // assistant shape. convertToLlm passes assistant messages through as-is.
   const content = invalidOnly
     ? [{ type: "text" as const, text: `${text} No tool was executed; send another prompt to continue.` }]
-    : [...message.content, { type: "text" as const, text }];
+    : [{ type: "text" as const, text }, ...message.content];
   return { ...message, content, stopReason: invalidOnly ? "stop" : "toolUse" };
 }
 
@@ -66,16 +81,123 @@ export async function guardMessageEnd(
   };
 }
 
-export default function (pi: ExtensionAPI) {
-  pi.on("message_end", async (event, ctx) => {
-    if (event.message.role !== "assistant") return;
+export function createToolCallHandler(config: GuardianConfig) {
+  return async (event: ToolCallEvent, ctx: ExtensionContext) => {
+    // Defense in depth: createMessageEndHandler already drops malformed tool calls
+    // (blank id or name) before they reach execution, but block any that still get
+    // here anyway (e.g. a replay path or a provider that streamed them directly).
+    // Optional chaining tolerates a *missing* id/name, not just a blank string.
+    if (!event.toolCallId?.trim() || !event.toolName?.trim()) {
+      return { block: true, reason: "[opl-guardian] Blocked a malformed tool call with a blank id or name." };
+    }
+
+    let toolPath: string | undefined;
+    if (isToolCallEventType("read", event)) toolPath = event.input.path;
+    else if (isToolCallEventType("write", event)) toolPath = event.input.path;
+    else if (isToolCallEventType("edit", event)) toolPath = event.input.path;
+    else if (isToolCallEventType("bash", event)) toolPath = event.input.command;
+
+    if (toolPath !== undefined) {
+      const blocked = getProtectedPathBlock(event.toolName, toolPath, config.protectedPaths.paths, ctx.cwd);
+      if (blocked) {
+        const reason = blocked.unresolved
+          ? `[opl-guardian] Cannot safely resolve path "${blocked.path}"; ${blocked.operation} denied by protected-path policy.`
+          : `[opl-guardian] Path "${blocked.path}" is protected (${blocked.operation} denied).`;
+        if (ctx.hasUI) ctx.ui.notify(reason, "warning");
+        return { block: true, reason };
+      }
+    }
+
+    if (!isToolCallEventType("bash", event) ||
+      !config.permissionGate.patterns.some((pattern) => pattern.test(event.input.command))) return undefined;
+
+    if (!ctx.hasUI) {
+      if (!config.permissionGate.blockWithoutUI) return undefined;
+      return { block: true, reason: "[opl-guardian] Command blocked because it matches a dangerous pattern and no confirmation UI is available." };
+    }
+
+    const command = event.input.command;
+    const preview = command.replace(/\s+/g, " ").trim();
+    // Fail closed: order "No" first so an accidental confirmation (or a replayed
+    // input event hitting a freshly-focused dialog) denies instead of approves.
+    // Only an explicit "Yes" selection approves the command.
+    const options = ["No", "Yes"];
+    if (ctx.mode === "rpc") {
+      try {
+        const choice = await ctx.ui.select(`Dangerous command: ${preview.slice(0, 256)}\nAllow?`, options);
+        if (choice === "Yes") return undefined;
+      } catch {
+        // A failed RPC dialog is not approval.
+      }
+      return { block: true, reason: "[opl-guardian] Command blocked; confirmation was declined or unavailable." };
+    }
+
+    const choice = await ctx.ui.select(`Dangerous command: ${preview.slice(0, 256)}\nAllow?`, options);
+    if (choice === "Yes") return undefined;
+    const reason = "[opl-guardian] Command blocked by user because it matches a dangerous pattern.";
+    ctx.ui.notify(reason, "warning");
+    return { block: true, reason };
+  };
+}
+
+export function createMessageEndHandler(config: GuardianConfig) {
+  return async (
+    event: MessageEndEvent,
+    ctx: Pick<ExtensionContext, "cwd" | "sessionManager" | "ui">,
+  ) => {
+    if (!config.dropMalformedToolCalls || event.message.role !== "assistant") return undefined;
     const guarded = await guardMessageEnd(event.message, {
       cwd: ctx.cwd,
       sessionId: ctx.sessionManager.getSessionId(),
     });
-    if (!guarded) return;
-
+    if (!guarded) return undefined;
     ctx.ui?.notify(guarded.diagnostic, "warning");
     return { message: guarded.message };
+  };
+}
+
+export function createSessionBeforeSwitchHandler(config: GuardianConfig) {
+  return async (event: SessionBeforeSwitchEvent, ctx: ExtensionContext) => {
+    let title: string;
+    let message: string;
+    if (event.reason === "new") {
+      if (!config.confirmDestructive.clearSession) return undefined;
+      title = "Clear session?";
+      message = "This will delete all messages in the current session.";
+    } else {
+      if (!config.confirmDestructive.switchWithUnsavedWork ||
+        !hasPendingUserWork(ctx.sessionManager.getBranch())) return undefined;
+      title = "Switch session?";
+      message = "You have unanswered work in the current session. Switch anyway?";
+    }
+
+    if (!ctx.hasUI) return config.confirmDestructive.blockWithoutUI ? { cancel: true } : undefined;
+    return await ctx.ui.confirm(title, message) ? undefined : { cancel: true };
+  };
+}
+
+export function createSessionBeforeForkHandler(config: GuardianConfig) {
+  return async (event: SessionBeforeForkEvent, ctx: ExtensionContext) => {
+    if (!config.confirmDestructive.forkSession) return undefined;
+    if (!ctx.hasUI) return config.confirmDestructive.blockWithoutUI ? { cancel: true } : undefined;
+    const confirmed = await ctx.ui.confirm(
+      `Fork from entry ${event.entryId.slice(0, 8)}?`,
+      "Create a new session branch from this point?",
+    );
+    return confirmed ? undefined : { cancel: true };
+  };
+}
+
+export default function (pi: ExtensionAPI) {
+  const { config, warnings } = loadGuardianConfig();
+  pi.on("session_start", async (_event, ctx) => {
+    if (warnings.length && ctx.hasUI) {
+      ctx.ui.notify(`[opl-guardian] Configuration warning(s):\n${warnings.join("\n")}`, "warning");
+    }
   });
+
+  pi.on("tool_call", createToolCallHandler(config));
+  pi.on("session_before_switch", createSessionBeforeSwitchHandler(config));
+  pi.on("session_before_fork", createSessionBeforeForkHandler(config));
+  pi.on("message_end", createMessageEndHandler(config));
 }

package/extensions/opl-guardian/policies.ts

@@ -0,0 +1,123 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { Op, PathEntry } from "./config.js";
+
+function resolveConfiguredPath(path: string, cwd: string): string {
+  if (path.startsWith("~/")) return resolve(homedir(), path.slice(2));
+  return resolve(cwd, path);
+}
+
+function physicalPath(path: string, depth = 0): string | undefined {
+  if (depth > 40) return undefined;
+  let current = path;
+  const missing: string[] = [];
+  while (true) {
+    let stat;
+    try {
+      stat = lstatSync(current);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") return undefined;
+      const parent = dirname(current);
+      if (parent === current) return undefined;
+      missing.unshift(basename(current));
+      current = parent;
+      continue;
+    }
+    try {
+      return resolve(realpathSync(current), ...missing);
+    } catch {
+      if (!stat.isSymbolicLink()) return undefined;
+      try {
+        return physicalPath(resolve(dirname(current), readlinkSync(current), ...missing), depth + 1);
+      } catch {
+        return undefined;
+      }
+    }
+  }
+}
+
+function isAbsoluteOrHomeRelative(path: string): boolean {
+  return isAbsolute(path) || path.startsWith("~/");
+}
+
+function matchesResolvedPath(toolPath: string, entryPath: string, cwd: string): boolean {
+  const resolvedTool = resolveConfiguredPath(toolPath, cwd);
+  const resolvedEntry = resolveConfiguredPath(entryPath, cwd);
+  const directoryPrefix = resolvedEntry.endsWith(sep) ? resolvedEntry : `${resolvedEntry}${sep}`;
+  return resolvedTool === resolvedEntry || resolvedTool.startsWith(directoryPrefix);
+}
+
+export function matchesProtectedPath(toolPath: string, entry: PathEntry, cwd: string): boolean {
+  if (isAbsoluteOrHomeRelative(entry.path)) {
+    return matchesResolvedPath(toolPath, entry.path, cwd);
+  }
+
+  const segment = entry.path.replace(/[\\/]+$/, "");
+  return toolPath.split(/[\\/]/).some((part) => part === segment);
+}
+
+export function hasPendingUserWork(entries: SessionEntry[]): boolean {
+  let pending = false;
+  for (const entry of entries) {
+    if (entry.type !== "message") continue;
+    if (entry.message.role === "assistant") pending = false;
+    else if (entry.message.role === "user") pending = true;
+  }
+  return pending;
+}
+
+export function getProtectedPathBlock(
+  toolName: string,
+  toolPath: string,
+  paths: PathEntry[],
+  cwd: string,
+): { path: string; operation: Op; unresolved?: boolean } | undefined {
+  if (toolName !== "read" && toolName !== "write" && toolName !== "edit" && toolName !== "bash") {
+    return undefined;
+  }
+
+  const operation = toolName;
+  const guardedPaths = paths.filter((entry) => entry.deny.includes(operation));
+  if (guardedPaths.length === 0) return undefined;
+  let normalizedTool = operation === "bash" ? toolPath : toolPath.replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, " ");
+  if (operation !== "bash") {
+    if (normalizedTool.startsWith("@")) normalizedTool = normalizedTool.slice(1);
+    if (normalizedTool.startsWith("file://")) {
+      try {
+        normalizedTool = fileURLToPath(normalizedTool);
+      } catch {
+        return { path: toolPath, operation, unresolved: true };
+      }
+    }
+  }
+  const canonicalTool = operation === "bash" ? undefined : physicalPath(resolveConfiguredPath(normalizedTool, cwd));
+  if (operation !== "bash" && !canonicalTool) {
+    return { path: toolPath, operation, unresolved: true };
+  }
+  for (const entry of guardedPaths) {
+    let matches: boolean;
+    if (operation === "bash") {
+      if (isAbsoluteOrHomeRelative(entry.path)) {
+        const resolvedEntry = resolveConfiguredPath(entry.path, cwd);
+        matches = toolPath.includes(entry.path) || toolPath.includes(resolvedEntry);
+      } else {
+        matches = toolPath.includes(entry.path.replace(/[\\/]+$/, ""));
+      }
+    } else {
+      matches = matchesProtectedPath(normalizedTool, entry, cwd) || matchesProtectedPath(canonicalTool!, entry, cwd);
+      if (!matches && isAbsoluteOrHomeRelative(entry.path)) {
+        const canonicalEntry = physicalPath(resolveConfiguredPath(entry.path, cwd));
+        if (!canonicalEntry) return { path: entry.path, operation, unresolved: true };
+        matches = matchesResolvedPath(canonicalTool!, canonicalEntry, cwd);
+      }
+    }
+
+    if (matches) return { path: entry.path, operation };
+  }
+
+  return undefined;
+}

package/extensions/opl-modes/README.md

@@ -9,7 +9,7 @@ Unified mode manager for Pi. It provides normal, read-only chat, read-only plann
 - `/plan` toggles plan mode, creates or loads a named plan, or accepts `/plan off`.
 - `/execute` selects or executes an existing plan; `/execute <name>` runs a named plan.
 - `--chat` and `--plan` start Pi in the corresponding read-only mode.
-- The configured cycle shortcut rotates through enabled visible modes. Execute mode is excluded from cycling because it requires an active plan. The default `shift+tab` is also Pi's built-in `app.thinking.cycle`, so both fire on one press; rebind either action in `~/.pi/agent/keybindings.json` (or pick another `shortcuts.cycleMode`) if you want them separate.
+- The configured cycle shortcut rotates through enabled visible modes. Execute mode is excluded from cycling because it requires an active plan. The default `ctrl+alt+m` does not collide with any built-in Pi keybinding; set `shortcuts.cycleMode` to rebind.
 
 Plans are Markdown files under `.pi/plans/` with the `plan-` filename prefix. A plan name must contain at least one letter or digit, so `/plan .` or `/plan --` is rejected instead of producing an untitled `plan-.md`. Loading a plan appends a TUI-only card (via `registerEntryRenderer`) so the plan text never enters the model context; the execute-mode system prompt is the single model-facing copy of the plan. `plan_complete` is available in execute mode and in any mode that sets `allowPlanComplete`. On completion, the plan file is deleted when `cleanup.cleanupOnComplete` is enabled. If execution ends without `plan_complete`, execute mode is exited automatically at Pi's `agent_before_settle` boundary (added in Pi 0.87.0) — but only when the run settled as `completed`: an aborted (ESC) or errored run keeps execute mode active so the plan can be resumed. On Pi < 0.87.0 this auto-exit is unavailable because the boundary is never emitted; `plan_complete` still exits the mode on any version.
 
@@ -17,7 +17,7 @@ Plans are Markdown files under `.pi/plans/` with the `plan-` filename prefix. A
 
 ### Mode behavior
 
-Chat and plan modes replace the active tools with configurable read-only tool lists and restrict Bash to safe inspection patterns. The allowlist is checked **per shell segment**, not just at the start of the command line: `&&`, `||`, a lone `&` (backgrounding), `|`, `;`, newlines, `$(...)`, backticks, and `<(`/`>(` each begin a segment, and every segment must match a safe pattern. Segment scanning is quote-aware, so `grep "a|b"` is one command, but a `$(...)` or backtick payload still runs inside double quotes and is split out and checked, so `echo "$(node -e ...)"` cannot hide behind the quoted argument. `cat f && node -e '...'`, `ls; python -c '...'`, and `cat x & rm -rf /` are blocked because their second segment is not safe-listed. Destructive patterns are still checked even when a command matches a safe pattern. The allowlist covers read-only inspection and text filters only: `awk`, `sed`, `xargs`, `perl`, `python`, and `env` are deliberately absent because they can write files, exec programs from their arguments, or dump API keys. Valid user-provided safe and destructive pattern arrays replace the built-in lists, rather than extending them. An explicit empty per-mode array replaces that policy with none; a malformed non-empty per-mode array is ignored and inherits the existing policy.
+Chat and plan modes replace the active tools with configurable read-only tool lists and restrict Bash to safe inspection patterns. The allowlist is checked **per shell segment**, not just at the start of the command line: `&&`, `||`, a lone `&` (backgrounding), `|`, `;`, newlines, `$(...)`, backticks, and `<(`/`>(` each begin a segment, and every segment must match a safe pattern. Segment scanning is quote-aware, so `grep "a|b"` is one command, but a `$(...)` or backtick payload still runs inside double quotes and is split out and checked, so `echo "$(node -e ...)"` cannot hide behind the quoted argument. `cat f && node -e '...'`, `ls; python -c '...'`, and `cat x & rm -rf /` are blocked because their second segment is not safe-listed. Destructive patterns are still checked even when a command matches a safe pattern. The allowlist covers read-only inspection and text filters only: `awk`, `sed`, `xargs`, `perl`, `python`, and `env` are deliberately absent because they can write files, exec programs from their arguments, or dump API keys. Valid user-provided safe and destructive pattern arrays replace the built-in lists, rather than extending them. An explicit empty per-mode array replaces that policy with none; a malformed non-empty per-mode array is ignored and inherits the existing policy. The top-level `bashPatterns.safePatterns`/`destructivePatterns` behave differently: an empty top-level array falls back to the built-in list (it cannot opt out), so opt a mode out with a per-mode `safePatterns: []` or `destructivePatterns: []` instead.
 
 The shared destructive base blocks file mutation primitives (`rm`, `rmdir`, `mv`, `cp`, `mkdir`, `touch`, `chmod`, `chown`, `tee`, `dd`, `shred`, `truncate`), `find -delete`/`-exec`/`-execdir`/`--exec-batch` and find's file-writing predicates (`-fprint`, `-fprint0`, `-fprintf`, `-fls`), any `--output` file (`sort --output`, `git log/diff/show --output`), `sort -o`/`tree -o` in any argument position, `fd -x`/`-X` (and clusters like `-Hx`), `rg --pre`, `jq`'s environment access (`jq -n env`, `$ENV`), `npm`/`yarn`/`pip` install and update forms including `npm audit fix`, state-changing `git` subcommands (including `branch -d`/`-D`/`-m`/`-M`/`-c`/`-C`/`--delete`/`--unset-upstream` and the writing `git remote` subcommands), `sudo`/`su`, `kill`/`pkill`, shell spawns, editors, `uniq`'s output operand (`uniq -c in.txt out.txt`; flags are not operands, so `uniq -c sorted.txt` stays a read), and every redirect that names a file - while descriptor duplication (`2>&1`, `>&2`, `>&-`) and a redirect whose target is exactly `/dev/null` are not writes and stay allowed (`> /dev/null/../tmp/x` is a write, so a path that merely starts with that prefix is blocked). `env` and `printenv` are not safe-listed, since they could dump provider API keys into the model context. Program-name entries are anchored to command position and matched per segment, so a read-only command that merely *mentions* a dangerous word in an argument (`du -sh`, `find . -name '*.sh'`, `ls cp/`, `cat mv.sh`, `git log --grep=rm`, `grep -rn 'touch' src`) stays allowed, and descriptor duplication (`2>&1`, `>&2`, `>&-`) is not mistaken for a file write. Every destructive pattern is tested against the command and each of its segments, with and without quotes/backslashes stripped, so `r"m"` and `-del"ete"` cannot dodge the list. That blocklist split deliberately ignores quotes, so an operator inside a quoted string (`echo "a > b"`) is over-blocked rather than trusted. This is still a heuristic backstop, not a process-isolation boundary: `npx` and any command whose *name* comes from an expansion are outside what a pattern list can catch.
 

package/extensions/opl-questionnaire/README.md

@@ -12,7 +12,7 @@ Adds a model-callable interactive questionnaire for discrete choices, preference
 
 - Renders one question as a compact option list and multiple questions as tabs with a final Submit tab.
 - Questions require an `id`, prompt, options, and optional label or free-text `allowOther` response.
-- Rejects duplicate IDs and questions that cannot be answered; returns `(no response)` for an empty custom answer.
+- Rejects duplicate IDs, blank IDs, and questions that cannot be answered; returns `(no response)` for an empty custom answer.
 - Returns structured answers containing question ID, selected value and label, custom-text flag, and option index where applicable.
 - Blocks submission until every multi-question prompt has an answer.
 - Returns a clear error in headless sessions so the model can use plain-text questions instead.