@openlines/opl-pi-sht 0.2.5 → 0.2.7

package/README.md

@@ -17,7 +17,7 @@ A portable collection of various Pi coding agent extensions. Repository director
 <div align="center">
 
 >
-> ### v0.2.5 (24 Sept 2026) - **Dev dependency floor**: `@earendil-works/pi-coding-agent` is now `^0.87.0` <br/>see [CHANGELOG.md](CHANGELOG.md) for more details.
+> ### v0.2.7 (29 Sept 2026) - **Unified `opl-guardian` safety**: adds configurable Bash confirmations, symlink-aware protected file-tool paths, destructive-session confirmations, and malformed-call filtering. <br/>See [CHANGELOG.md](CHANGELOG.md) for details.
 >
 
 </div>
@@ -84,7 +84,7 @@ Copy mode overwrites matching destinations. Link mode skips existing destination
 | [`opl-webaccess`](extensions/opl-webaccess/README.md)         | Search plus readable URL/PDF retrieval with session recovery.                                                                                                                                                                | `web_search`, `fetch_content`, `get_search_content`; `opl-webaccess.json`.                                     |
 | [`opl-browser`](extensions/opl-browser/README.md)             | Chromium automation via Playwright with structured extraction of rendered pages; single dispatcher tool replacing the chrome-devtools MCP.                                                                                   | `browser` (action-based); `opl-browser.json`.                                                                  |
 | [`opl-ctxtrim`](extensions/opl-ctxtrim/README.md)             | Trims verbose`ctx_*` tool-schema descriptions on outbound provider requests (~67% smaller schema, ~4,700-6,300 tokens/request). Built specifically for the [context-mode](https://github.com/mksglu/context-mode) extension. | No commands/tools; no config.                                                                                  |
-| [`opl-guardian`](extensions/opl-guardian/README.md)           | Drops malformed assistant tool calls before session persistence or replay, with project-local JSONL evidence. | No commands/tools; no config.                                                                                  |
+| [`opl-guardian`](extensions/opl-guardian/README.md)           | Configurable tool and session safety: dangerous-Bash confirmation, protected paths, destructive-session confirmation, and malformed-call filtering. | No commands/tools; `opl-guardian.json`. |
 | [`opl-todo`](extensions/opl-todo/README.md)                   | Branch-aware task tool, overlay, and task list.                                                                                                                                                                              | `todo`, `/todos`; `opl-todo.json`.                                                                             |
 | [`opl-questionnaire`](extensions/opl-questionnaire/README.md) | Interactive structured-choice tool.                                                                                                                                                                                          | `questionnaire`; no config.                                                                                    |
 | [`opl-input`](extensions/opl-input/README.md)                 | Configurable replacement editor - enhanced [pikit chat-input](https://github.com/adrianapan/pikit) (because pet is life, and configurable). ![pet](images/ss-input-pet.png)                                                                                   | No commands/tools;`opl-input.json`.                                                                            |
@@ -116,7 +116,7 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 - **`opl-modes`** chat and plan modes swap the active toolset for read-only lists and gate Bash to safe inspection patterns **per shell segment**, so `cat f && node -e '...'`, `cat x & rm -rf /tmp/x`, and `echo "$(node -e ...)"` can no longer ride the first command's allowance. Destructive checks still fire inside otherwise-safe commands (anchored to command position, so `du -sh` and `find . -name '*.sh'` stay allowed; `find -delete`, `find -fprint`, `git log --output`, `sort -o`, `npm audit fix`, `git clean`, `sudo`, and quote-obfuscated `r"m"`/`-del"ete"` are blocked; `env`/`printenv` are not safe-listed). The plan to execute lifecycle keeps exploration and mutation cleanly separated. Add custom modes (like below) for your workflow needs. Execute-mode auto-exit needs pi >= 0.87.0 (the `agent_before_settle` boundary).
 ![custom mode sample](images/ss-mode-custom.png)
 - `load_tools` activation is bounded by the current mode, so a read-only mode cannot be tricked into enabling a write-capable tool.
-- **`opl-guardian`** stops a malformed provider tool-call record from poisoning the session: it removes calls missing an ID or name before Pi persists or replays them, while preserving dropped records in `err/guardian.jsonl` for an upstream report.
+- **`opl-guardian`** combines configurable safety checks in one extension: it confirms dangerous Bash commands in the terminal or over RPC, blocks configured protected paths for file tools (including symlink targets), and confirms session clear/switch-with-pending-work/fork actions. Without a UI, configured dangerous commands and session actions block by default. It also removes malformed provider tool calls before persistence or replay and records incidents in `err/guardian.jsonl`. Protected-path Bash matching is literal best-effort, not shell sandboxing.
 
 
 ### Move through work faster
@@ -150,7 +150,7 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 | Run the agent safely on real repos | `opl-modes` (pulls in the `opl-input` + `opl-footer` UI bundle), `opl-guardian` |
 | Research and drive the web         | `opl-webaccess`, `opl-browser`                                  |
 | Choose models with data            | `opl-simplebench`                                               |
-| The full, coordinated experience   | all ten                                                         |
+| The full, coordinated experience   | all eleven                                                      |
 
 Selecting `opl-footer`, `opl-input`, or `opl-modes` installs all three, because they share active-mode state.
 
@@ -171,7 +171,7 @@ Installing extensions adds tool schemas (name + description + JSON parameters) t
 | `opl-init` | command only (no tool) | ~0 |
 | `opl-input` | UI only | ~0 |
 | `opl-footer` | UI only | ~0 |
-| `opl-guardian` | none (session-integrity guard) | ~0 |
+| `opl-guardian` | none (tool/session safety; no added tool schemas) | ~0 |
 | `opl-ctxtrim` | none (payload transformer) | net negative |
 
 Command descriptions add roughly another ~120 tokens collectively, and only if your build surfaces them in the prompt or help block.
@@ -195,9 +195,10 @@ The fixed cost of a full install is small and paid once per session, then cached
 
 Copy applicable files from [`configs/`](configs/) to `~/.pi/agent/configs/`. For a Pi package installation, the source directory is `~/.pi/agent/npm/node_modules/@openlines/opl-pi-sht/configs/` (npm) or `~/.pi/agent/git/github.com/linellazatin/opl-pi-sht/configs/` (Git):
 
-- `opl-footer.json`, `opl-input.json`, `opl-modes.json`, `opl-todo.json`, `opl-webaccess.json`
+- `opl-footer.json`, `opl-input.json`, `opl-modes.json`, `opl-todo.json`, `opl-webaccess.json`, `opl-guardian.json`
 - `opl-browser` has optional configuration (`opl-browser.json`); all fields default, so it works without any config file.
 - `opl-simplebench` has optional `opl-simplebench.json`; copy `configs/opl-simplebench.json.sample` to configure DDGS/SearXNG research and llama metadata endpoints.
+- `opl-guardian` has an optional `opl-guardian.json`; copy `configs/opl-guardian.json.sample` and manually migrate any old permission-gate or protected-path settings. It does not load legacy files. Configured `permissionGate.patterns` replace the defaults, so copied live patterns do not automatically inherit later default-rule updates.
 - `opl-init` and `opl-questionnaire` have no external configuration.
 - Config files must be valid JSON, with no comments or trailing commas beyond deliberate `_comment` keys.
 - `opl-modes` owns active-mode appearance. Each mode's `appearance.prefix`, `prefixColor`, and `borderColor` style `opl-input`; `appearance.modeColor` styles `opl-footer`'s unified mode label. Renderers retain hardcoded fallbacks.

package/configs/opl-guardian.json.sample

@@ -0,0 +1,28 @@
+{
+  "_comment": "Copy to ~/.pi/agent/configs/opl-guardian.json and customize. This replaces standalone permission-gate, protected-paths, and confirm-destructive settings.",
+  "permissionGate": {
+    "patterns": [
+      "\\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|$)"
+    ],
+    "blockWithoutUI": true
+  },
+  "protectedPaths": {
+    "paths": [
+      { "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"] }
+    ]
+  },
+  "confirmDestructive": {
+    "clearSession": true,
+    "switchWithUnsavedWork": true,
+    "forkSession": true,
+    "blockWithoutUI": true
+  },
+  "dropMalformedToolCalls": true
+}

package/extensions/opl-footer/README.md

@@ -75,7 +75,7 @@ See the tracked [`configs/opl-footer.json.sample`](../../configs/opl-footer.json
 | `model` | Model name in pink + `(provider)` in dim | No icon; provider omitted if unavailable |
 | `path` | Current working directory | `segmentOptions.path.mode`: `"full"` (default) · `"abbreviated"` · `"basename"` |
 | `git` | Git branch and dirty indicators | `showBranch`, `showStaged`, `showUnstaged`, `showUntracked` (all bool) |
-| `context_pct` | Gradient bar + `X.X%` + max tokens | Bar fully configurable via `segmentOptions.contextBar` (see below). % and max tokens use `contextLabel` colour. Max tokens formatted with K/M suffix (e.g. `128k`, `2M`). Usage comes from `ctx.getContextUsage()`; when Pi reports it as unknown (right after compaction or a context edit) the segment renders an explicit `(--%)` instead of a stale value. Set `DEBUG_PCT` in `context.ts` to a number (0–100) to pin the bar at a fixed value for visual testing. |
+| `context_pct` | Gradient bar + `X.X%` + max tokens | Bar fully configurable via `segmentOptions.contextBar` (see below). % and max tokens use `contextLabel` colour. Max tokens formatted with K/M suffix (e.g. `128k`, `2M`). Usage comes from `ctx.getContextUsage()`; when Pi reports it as unknown right after compaction, the segment estimates the rebuilt projection with Pi’s `estimateTokens()` and marks the bar and values with `≈` until a fresh assistant response provides exact usage. If no projection is available, it renders `(--%)` rather than a stale value. Set `DEBUG_PCT` in `context.ts` to a number (0–100) to pin the bar at a fixed value for visual testing. |
 | `cost` | `$<amount>` (4 decimals, e.g. `$0.0123`) | `$` dim, amount in `cost` colour (`muted` by default). Four decimals keep cheap local or short sessions distinguishable instead of pinning at `$0.00`. Shows dim `(no pricing)` when the session total is zero on a non-local model (provider has no pricing configured), and `(local model)` for local models |
 | `thinking` | `Thinking: <LEVEL>` | Dim label, CAPS level with per-level colour; always visible |
 | `mode_switcher` | Unified active mode label | Reads state published by `opl-modes`; `appearance.modeColor` controls the mode value, with hardcoded `muted` fallback |

package/extensions/opl-footer/index.ts

@@ -5,6 +5,7 @@ import type { TUI } from "@earendil-works/pi-tui";
 
 import type { SegmentContext, StatusLineSegmentId, UsageStats, SessionStats, SessionEvent, ThinkingLevelEvent, AssistantMessageEvent, ToolResultEvent, UserBashEvent } from "./types.js";
 import { renderSegment } from "./segments/index.js";
+import { estimateContextUsage } from "./segments/context.js";
 import { createAgentStatusTracker } from "./segments/status.js";
 import { getGitStatus, invalidateGitStatus, invalidateGitBranch } from "./git-status.js";
 import { getEffectiveConfig } from "./config.js";
@@ -278,12 +279,16 @@ export default function footer(pi: ExtensionAPI) {
       ? thinkingEvents.reduce((_, e) => e.thinkingLevel ?? "off", "off")
       : null;
 
-    // Prefer Pi's canonical context usage (0.87), which is null when usage is unknown
-    // (e.g. right after compaction, before the next assistant reply) or after a context
-    // edit. Fall back to the model's window when unavailable.
+    // Prefer Pi's canonical context usage (0.87). Immediately after compaction it is
+    // null until the next assistant reply, so estimate the rebuilt projection instead.
     const usage = typeof ctx.getContextUsage === "function" ? ctx.getContextUsage() : undefined;
     const contextWindow = usage?.contextWindow ?? ctx.model?.contextWindow ?? 0;
-    const contextPercent = usage?.percent ?? null;
+    const projectedMessages = ctx.sessionManager?.buildSessionProjection?.().messages;
+    const estimatedContextUsage = usage?.percent === null && contextWindow > 0 && projectedMessages
+      ? estimateContextUsage(projectedMessages, contextWindow)
+      : null;
+    const contextPercent = usage?.percent ?? estimatedContextUsage?.percent ?? null;
+    const contextEstimated = estimatedContextUsage !== null;
 
     // Get git status (cached). Skip the probes entirely when no visible row renders the
     // git segment — otherwise an unused cell keeps spawning git once per second.
@@ -322,6 +327,7 @@ export default function footer(pi: ExtensionAPI) {
       sessionId: ctx.sessionManager?.getSessionId?.(),
       usageStats,
       contextPercent,
+      contextEstimated,
       contextWindow,
       usingSubscription,
       sessionStartTime,

package/extensions/opl-footer/segments/context.ts

@@ -1,3 +1,5 @@
+import { estimateTokens } from "@earendil-works/pi-coding-agent";
+
 import type { RenderedSegment, SegmentContext } from "../types.js";
 import { applyColor, resolveColorToRgb } from "../theme.js";
 import { color } from "./helpers.js";
@@ -19,6 +21,14 @@ export function lerp(a: number, b: number, t: number): number {
   return Math.round(a + (b - a) * t);
 }
 
+export function estimateContextUsage(
+  messages: Parameters<typeof estimateTokens>[0][],
+  contextWindow: number,
+): { tokens: number; percent: number } {
+  const tokens = messages.reduce((total, message) => total + estimateTokens(message), 0);
+  return { tokens, percent: (tokens / contextWindow) * 100 };
+}
+
 function positionColor(
   pos: number,
   barWidth: number,
@@ -75,7 +85,9 @@ export const contextPctSegment = {
 
     // Show: (00.00%) 99999 / 99999
     const used = Math.round((pct / 100) * ctx.contextWindow);
-    const pctLabel = `(${pct.toFixed(2)}%) ${formatTokens(used)} / ${formatTokens(ctx.contextWindow)}`;
+    const pctLabel = ctx.contextEstimated
+      ? `≈${pct.toFixed(2)}%  ≈${formatTokens(used)} / ${formatTokens(ctx.contextWindow)}`
+      : `(${pct.toFixed(2)}%) ${formatTokens(used)} / ${formatTokens(ctx.contextWindow)}`;
     const pctStr = color(ctx, "contextLabel", pctLabel);
 
     return { content: `${bar} ${pctStr}`, visible: true };

package/extensions/opl-footer/types.ts

@@ -119,6 +119,7 @@ export interface SegmentContext {
   sessionId: string | undefined;
   usageStats: UsageStats;
   contextPercent: number | null;
+  contextEstimated: boolean;
   contextWindow: number;
   usingSubscription: boolean;
   sessionStartTime: number;

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. 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; 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.
 
-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, 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/index.ts

@@ -1,13 +1,25 @@
 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 { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, SelectList, Spacer, Text, type SelectItem } from "@earendil-works/pi-tui";
 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");
 
@@ -66,16 +78,156 @@ 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) => {
+    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;
+    if (ctx.mode === "rpc") {
+      const preview = command.replace(/\s+/g, " ").trim();
+      try {
+        const choice = await ctx.ui.select(`Dangerous command: ${preview.slice(0, 256)}\nAllow?`, ["Yes", "No"]);
+        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 items: SelectItem[] = [
+      { value: "yes", label: "Yes" },
+      { value: "no", label: "No" },
+    ];
+    const choice = await ctx.ui.custom<string | null>((tui, theme, keybindings, done) => {
+      const border = new DynamicBorder((text: string) => theme.fg("border", text));
+      const label = new Text(theme.fg("text", "Dangerous command detected:"), 1, 0);
+      const preview = command.replace(/\s+/g, " ").trim();
+      const commandText = new Text(theme.fg("error", preview.length > 256 ? `${preview.slice(0, 256)}…` : preview), 1, 0);
+      const question = new Text(theme.fg("text", "Allow this command?"), 1, 0);
+      const selectList = new SelectList(items, Math.min(items.length, 10), {
+        selectedPrefix: (text) => theme.fg("accent", text),
+        selectedText: (text) => theme.fg("accent", text),
+        description: (text) => theme.fg("muted", text),
+        scrollInfo: (text) => theme.fg("dim", text),
+        noMatch: (text) => theme.fg("warning", text),
+      });
+      selectList.onSelect = (item) => done(item.value);
+      selectList.onCancel = () => done(null);
+
+      const container = new Container();
+      container.addChild(border);
+      container.addChild(new Spacer());
+      container.addChild(label);
+      container.addChild(commandText);
+      container.addChild(new Spacer());
+      container.addChild(question);
+      container.addChild(selectList);
+      container.addChild(new Spacer());
+      container.addChild(new Text(theme.fg("dim", "↑↓ navigate  enter select  esc cancel"), 1, 0));
+      container.addChild(border);
+
+      return {
+        render(width: number) { return container.render(width); },
+        invalidate() { container.invalidate(); },
+        handleInput(data: string) {
+          if (keybindings.matches(data, "app.tools.expand")) {
+            ctx.ui.setToolsExpanded(!ctx.ui.getToolsExpanded());
+            return;
+          }
+          selectList.handleInput(data);
+          tui.requestRender();
+        },
+      };
+    });
+
+    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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openlines/opl-pi-sht",
-  "version": "0.2.5",
-  "description": "opl-pi-sht (shouldHaveThat) Pi coding-agent extension kit: token-efficient context, safe modes, fingerprinted /init, model benchmarking, web access, and browser automation.",
+  "version": "0.2.7",
+  "description": "opl-pi-sht (shouldHaveThat) Pi coding-agent extension kit: token-efficient context, tool and session safety, fingerprinted /init, model benchmarking, web access, and browser automation.",
   "repository": {
     "type": "git",
     "url": "https://github.com/linellazatin/opl-pi-sht.git"