@openlines/opl-pi-sht 0.2.11 → 0.3.0

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

@@ -13,6 +13,7 @@ import { planModeSegment } from "./plan-mode.js";
 import { chatModeSegment } from "./chat-mode.js";
 import { modeSwitcherSegment } from "./mode-switcher.js";
 import { sessionStatsSegment, perfStatsSegment } from "./session-stats.js";
+import { compactionsSegment } from "./compactions.js";
 import { statusSegment } from "./status.js";
 import { codexUsageSegment } from "./codex-usage.js";
 import { openRouterUsageSegment } from "./openrouter-usage.js";
@@ -37,6 +38,7 @@ const SEGMENTS = {
   chat_mode: chatModeSegment,
   mode_switcher: modeSwitcherSegment,
   session_stats: sessionStatsSegment,
+  compactions: compactionsSegment,
   perf_stats: perfStatsSegment,
   status: statusSegment,
   codex_usage: codexUsageSegment,

package/extensions/opl-footer/segments/mode-switcher.ts

@@ -6,8 +6,21 @@ interface AgentModeState {
   appearance?: { modeColor?: string };
 }
 
+/**
+ * Written by `opl-modes`, which may not be installed, and may be written by anything else
+ * that claims the name. Only a `{ mode: string }` is honoured; anything else renders nothing
+ * rather than throwing inside the footer's render loop.
+ */
 function readAgentModeState(): AgentModeState | undefined {
-  return (globalThis as Record<string, unknown>).__agentMode as AgentModeState | undefined;
+  const state = (globalThis as Record<string, unknown>).__agentMode as unknown;
+  if (!state || typeof state !== "object") return undefined;
+  const { mode, appearance } = state as { mode?: unknown; appearance?: unknown };
+  if (typeof mode !== "string" || !mode) return undefined;
+  const modeColor =
+    appearance && typeof appearance === "object"
+      ? (appearance as { modeColor?: unknown }).modeColor
+      : undefined;
+  return { mode, ...(typeof modeColor === "string" ? { appearance: { modeColor } } : {}) };
 }
 
 export const modeSwitcherSegment = {

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

@@ -8,7 +8,7 @@ export const pathSegment = {
     const opts = ctx.options.path ?? {};
     const mode = opts.mode ?? "basename";
 
-    let pwd = process.cwd();
+    let pwd = ctx.cwd || process.cwd();
     const home = process.env.HOME || process.env.USERPROFILE;
 
     if (mode === "basename") {

package/extensions/opl-footer/segments/plan-mode.ts

@@ -6,8 +6,15 @@ interface PlanModeState {
   mode: string;
 }
 
+/**
+ * Written by `opl-modes`, which may not be installed. Only a `{ mode: string }` is honoured;
+ * anything else reads as "no state", so the segment stays invisible instead of throwing.
+ */
 function readPlanModeState(): PlanModeState | undefined {
-  return (globalThis as Record<string, unknown>).__planMode as PlanModeState | undefined;
+  const state = (globalThis as Record<string, unknown>).__planMode as unknown;
+  if (!state || typeof state !== "object") return undefined;
+  const mode = (state as { mode?: unknown }).mode;
+  return typeof mode === "string" ? { mode } : undefined;
 }
 
 export const planModeSegment = {

package/extensions/opl-footer/theme.ts

@@ -5,7 +5,8 @@ import type { ColorScheme, ColorValue, SemanticColor } from "./types.js";
 // their absence signals "use rainbow" in thinking.ts.
 const DEFAULT_COLORS: ColorScheme = {
   pi: "accent",
-  model: "#c07898",
+  // model: "#c07898",
+  model: "accent",
   path: "dim",
   git: "success",
   gitDirty: "warning",
@@ -128,5 +129,7 @@ export function resolveColorToRgb(
   }
   const match = probed.match(/\x1b\[38;2;(\d+);(\d+);(\d+)m/);
   if (!match) return null;
-  return { r: parseInt(match[1]), g: parseInt(match[2]), b: parseInt(match[3]) };
+  const [r, g, b] = [match[1], match[2], match[3]];
+  if (r === undefined || g === undefined || b === undefined) return null;
+  return { r: parseInt(r, 10), g: parseInt(g, 10), b: parseInt(b, 10) };
 }

package/extensions/opl-footer/types.ts

@@ -54,6 +54,7 @@ export type StatusLineSegmentId =
   | "chat_mode"
   | "mode_switcher"
   | "session_stats"
+  | "compactions"
   | "perf_stats"
   | "status"
   | "codex_usage"
@@ -127,6 +128,8 @@ export interface SegmentContext {
   contextWindow: number;
   usingSubscription: boolean;
   sessionStartTime: number;
+  /** Session directory (`ExtensionContext.cwd`): the base the Path segment renders. */
+  cwd: string;
   git: GitStatus;
   options: StatusLineSegmentOptions;
   width: number;
@@ -134,6 +137,7 @@ export interface SegmentContext {
   colors: ColorScheme;
   icons: IconSet;
   sessionStats: SessionStats;
+  compactions: number;
   agentStatus: AgentStatus;
   codexUsage: CodexUsageSnapshot | null;
   openRouterUsage: OpenRouterUsageSnapshot | null;

package/extensions/opl-guardian/README.md

@@ -7,9 +7,11 @@ A configurable session and tool safety extension. `opl-guardian` filters malform
 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.
 
 - `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.
+- `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 matches path-shaped words in the command, resolved against the session directory and through symlinks. Absolute and `~/` entries match resolved paths and descendants for file tools, and are matched in Bash by the same resolution plus the final path segment. An empty list disables path rules. Entries name exact paths: `.env` does not cover `.env.local` or `.env.production`, and no glob syntax is supported — list each path you want denied.
 - `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.
+- `logging.incidentFile` chooses where incidents go. It defaults to `null`, which is `<agent dir>/guardian-incidents.jsonl`; a relative path also resolves under the agent dir, an absolute or `~/` path is used as given, and `false` stops writing. The session cwd is never consulted, so opening a repository cannot leave a log inside it.
+- `logging.maxBytes` defaults to `262144`. Before an append that would pass it, the current log moves to `guardian-incidents.jsonl.1` and a fresh file starts: one generation of history, nothing older is kept.
 
 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.
 
@@ -19,11 +21,15 @@ If migrating from the standalone extensions, manually move their settings into t
 
 ### Dangerous Bash commands
 
-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.
+The default patterns cover recursive `rm` flags (including `-rf`, `-fr`, and separate `-f -r`), `sudo`, `chmod`/`chown` to mode `777`, `printenv`, and `env` **as a command** — `env`, `env | grep PATH`, `; env`, `$(env)` prompt, while `grep -n 'env' README.md` or `cat config/env.ts` do not. Matching commands require confirmation. Without a confirmation UI they are blocked by default.
 
 ### Protected paths
 
-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.
+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 rules match **words**, not substrings: the command is split on whitespace, quotes, and shell punctuation, and each word is compared to the entry by path segment and by resolution against the session directory, including symlinks. Blocked, measured: `cat .env`, `cat /project/.env`, `head -2 .env | tail -1`, `git show HEAD:.env`, `python -c 'open(".env")'`, `x=".env"; cat $x`, `export F=$(cat .env)`, and `cat alias` where `alias` is a symlink to the protected file. Allowed, measured: `grep -rn "process.env" src`, `cat .env.example`, `cat .env.local`, `ls env` — the older substring rule blocked all of those too, which made the rule impossible to live with.
+
+Entries name exact paths and there is no glob syntax: `.env` does not cover `.env.local` or `.env.production`, so list each path you want denied. Two further limits are structural, so Bash protection stays **advisory** while `read`/`write`/`edit` is where the guarantee lives. A name that never appears whole in the text cannot be recognised — `cat .en""v` and `$(printf '\x2eenv')` pass — and a glob names no single file to check (`rm -f .env*`). Because words resolve against the session directory, `cd elsewhere && cat .env` is judged as if the `cd` had not happened.
 
 ### Destructive session actions
 
@@ -33,15 +39,21 @@ Starting a new session, resuming another session with a pending user message, an
 
 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.
 
+A Bash call whose `command` is not a string is blocked outright rather than coerced: there is no command to inspect, and matching a coerced array (`String(["rm","-rf"])` reads as `rm,-rf`) would confirm the wrong thing.
+
 ## Forensic JSONL
 
 Each malformed-call incident appends one JSON object to:
 
 ```text
-<project cwd>/err/guardian.jsonl
+<agent dir>/guardian-incidents.jsonl
 ```
 
-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.
+That is pi's own directory (`PI_CODING_AGENT_DIR`, default `~/.pi/agent`), not the project: an untracked `err/` directory inside whatever repository a session happens to open is noise, and it would hold fragments of provider payloads. Override the location with `logging.incidentFile`, or set it to `false` to keep no log at all.
+
+Records carry the timestamp (falling back to the current time when a provider omitted or zeroed it), session/project/provider/model metadata, and one summary per dropped tool call: tool name, sorted argument *key* names, and the byte size of the arguments. Argument values are never recorded - a malformed call can carry file contents, commands or credentials, and those belong in the session transcript, not a log file. So the log holds no prompts, assistant text, thinking, or tool results, but argument key names are still names: a tool that labels an argument after its content would show up here.
+
+Treat it as local diagnostic data. 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
 

package/extensions/opl-guardian/config.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export type Op = "read" | "write" | "edit" | "bash";
 
@@ -9,6 +10,18 @@ export interface PathEntry {
   deny: Op[];
 }
 
+export interface GuardianLogging {
+  /**
+   * Where a malformed-call incident is recorded. Never resolved against the session cwd:
+   * forensics in the open repository would be untracked noise holding provider fragments.
+   * `null` uses `<agent dir>/guardian-incidents.jsonl`, a relative value resolves under the
+   * agent dir, `~` expands to the home directory, and `false` stops writing.
+   */
+  incidentFile: string | false | null;
+  /** Rotate the log to `<file>.1` before an append that would pass this many bytes. */
+  maxBytes: number;
+}
+
 export interface GuardianConfig {
   permissionGate: {
     patterns: RegExp[];
@@ -24,14 +37,20 @@ export interface GuardianConfig {
     blockWithoutUI: boolean;
   };
   dropMalformedToolCalls: boolean;
+  logging: GuardianLogging;
 }
 
+export const DEFAULT_LOGGING: GuardianLogging = {
+  incidentFile: null,
+  maxBytes: 256 * 1024,
+};
+
 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|$)",
+  "(?:^|[;&|()\\n])\\s*env(?:[\\s)|]|$)",
 ];
 
 const DEFAULT_PATHS: PathEntry[] = [
@@ -54,9 +73,13 @@ export const DEFAULT_CONFIG: GuardianConfig = {
     blockWithoutUI: true,
   },
   dropMalformedToolCalls: true,
+  logging: { ...DEFAULT_LOGGING },
 };
 
-const CONFIG_PATH = join(homedir(), ".pi", "agent", "configs", "opl-guardian.json");
+/** Resolved per call so a custom `PI_AGENT_DIR` (pi's own agent dir) is honoured. */
+export function configPath(): string {
+  return join(getAgentDir(), "configs", "opl-guardian.json");
+}
 const OPS = new Set<Op>(["read", "write", "edit", "bash"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -72,6 +95,7 @@ function cloneDefaults(): GuardianConfig {
     protectedPaths: { paths: DEFAULT_PATHS.map((entry) => ({ ...entry, deny: [...entry.deny] })) },
     confirmDestructive: { ...DEFAULT_CONFIG.confirmDestructive },
     dropMalformedToolCalls: true,
+    logging: { ...DEFAULT_LOGGING },
   };
 }
 
@@ -173,18 +197,60 @@ export function parseGuardianConfig(value: unknown): { config: GuardianConfig; w
     }
   }
 
+  if (value.logging !== undefined) {
+    if (!isRecord(value.logging)) {
+      warnings.push("Invalid logging section; using defaults.");
+    } else {
+      const file = value.logging.incidentFile;
+      if (file === undefined || file === null) {
+        config.logging.incidentFile = DEFAULT_LOGGING.incidentFile;
+      } else if (file === false || typeof file === "string") {
+        config.logging.incidentFile = file;
+      } else {
+        warnings.push("logging.incidentFile must be a path or false; using the agent-directory default.");
+      }
+
+      const maxBytes = value.logging.maxBytes;
+      if (maxBytes === undefined) {
+        config.logging.maxBytes = DEFAULT_LOGGING.maxBytes;
+      } else if (typeof maxBytes === "number" && Number.isFinite(maxBytes) && maxBytes >= 1024) {
+        config.logging.maxBytes = Math.floor(maxBytes);
+      } else {
+        warnings.push("logging.maxBytes must be a number of at least 1024; using the default.");
+      }
+    }
+  }
+
   return { config, warnings };
 }
 
+/**
+ * Resolve where incident records go. Absolute paths are used as given, `~/` expands to the
+ * home directory, and anything else lands under pi's agent directory - the session cwd is
+ * never an input, so opening a repository cannot leave a log file inside it.
+ */
+export function incidentLogPath(logging: GuardianLogging): string | null {
+  if (logging.incidentFile === false) return null;
+  const value = logging.incidentFile;
+  if (typeof value !== "string" || value.trim() === "") {
+    return join(getAgentDir(), "guardian-incidents.jsonl");
+  }
+  const trimmed = value.trim();
+  if (trimmed.startsWith("~/")) return resolve(homedir(), trimmed.slice(2));
+  if (isAbsolute(trimmed)) return trimmed;
+  return join(getAgentDir(), trimmed);
+}
+
 export function loadGuardianConfig(): { config: GuardianConfig; warnings: string[] } {
+  const file = configPath();
   let raw: string;
   try {
-    raw = readFileSync(CONFIG_PATH, "utf8");
+    raw = readFileSync(file, "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return parseGuardianConfig(undefined);
     return {
       config: cloneDefaults(),
-      warnings: [`Could not read ${CONFIG_PATH}; using defaults.`],
+      warnings: [`Could not read ${file}; using defaults.`],
     };
   }
 
@@ -193,7 +259,7 @@ export function loadGuardianConfig(): { config: GuardianConfig; warnings: string
   } catch {
     return {
       config: cloneDefaults(),
-      warnings: [`Invalid JSON in ${CONFIG_PATH}; using defaults.`],
+      warnings: [`Invalid JSON in ${file}; using defaults.`],
     };
   }
 }

package/extensions/opl-guardian/guardian.ts

@@ -5,6 +5,13 @@ export interface IncidentContext {
   cwd: string;
 }
 
+export interface RemovedToolCallSummary {
+  name: string;
+  argumentKeys: string[];
+  /** Size of the arguments that were dropped; the values themselves are never recorded. */
+  argumentsBytes: number;
+}
+
 export interface GuardianIncident {
   timestamp: string;
   kind: "malformed_tool_call";
@@ -14,7 +21,7 @@ export interface GuardianIncident {
   model: string;
   responseId?: string;
   action: "dropped";
-  removedToolCalls: ToolCall[];
+  removedToolCalls: RemovedToolCallSummary[];
 }
 
 export interface GuardResult {
@@ -26,20 +33,28 @@ function hasValue(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0;
 }
 
-export function isMalformedToolCall(block: unknown): block is ToolCall {
-  if (!block || typeof block !== "object" || (block as { type?: unknown }).type !== "toolCall") {
-    return false;
-  }
-  const toolCall = block as ToolCall;
-  return !hasValue(toolCall.id) || !hasValue(toolCall.name);
+function isToolCallBlock(block: unknown): block is ToolCall {
+  return !!block && typeof block === "object" && (block as { type?: unknown }).type === "toolCall";
+}
+
+/** A toolCall block whose id or name is missing: pi cannot route it, and leaving it in the
+ *  message fails the whole turn, so the guardian drops it. */
+export function isMalformedToolCall(block: unknown): boolean {
+  return isToolCallBlock(block) && (!hasValue(block.id) || !hasValue(block.name));
+}
+
+// The same test as a type predicate, so `filter` can type the removed blocks as ToolCall[]
+// without narrowing ToolCall out of the kept content array.
+function isMalformedToolCallBlock(block: unknown): block is ToolCall {
+  return isMalformedToolCall(block);
 }
 
 export function guardAssistantMessage(message: AssistantMessage): GuardResult | undefined {
-  const removedToolCalls = message.content.filter(isMalformedToolCall);
+  const removedToolCalls = message.content.filter(isMalformedToolCallBlock);
   if (removedToolCalls.length === 0) return undefined;
 
   const content = message.content.filter((block) => !isMalformedToolCall(block));
-  const hasValidToolCall = content.some((block) => block.type === "toolCall");
+  const hasValidToolCall = content.some(isToolCallBlock);
 
   return {
     removedToolCalls,
@@ -69,6 +84,23 @@ export function buildIncidentRecord(
     model: message.model,
     ...(message.responseId ? { responseId: message.responseId } : {}),
     action: "dropped",
-    removedToolCalls,
+    removedToolCalls: removedToolCalls.map(summarizeRemovedToolCall),
   };
 }
+
+/**
+ * Incident records are kept for diagnostics, not as a copy of the transcript: argument
+ * *names* say which call went wrong, while the values can carry file contents, commands or
+ * credentials straight out of the session.
+ */
+export function summarizeRemovedToolCall(call: ToolCall): RemovedToolCallSummary {
+  const args = (call as { arguments?: unknown }).arguments;
+  const keys = args && typeof args === "object" ? Object.keys(args as Record<string, unknown>).sort() : [];
+  let bytes = 0;
+  try {
+    bytes = Buffer.byteLength(JSON.stringify(args ?? {}));
+  } catch {
+    bytes = -1; // not serializable; the size is unknown but nothing is leaked either
+  }
+  return { name: hasValue(call.name) ? call.name : "(unnamed)", argumentKeys: keys, argumentsBytes: bytes };
+}

package/extensions/opl-guardian/index.ts

@@ -8,10 +8,16 @@ import {
   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 { appendFile, chmod, mkdir, rename, stat } from "node:fs/promises";
+import { dirname } from "node:path";
 
-import { loadGuardianConfig, type GuardianConfig } from "./config.js";
+import {
+  DEFAULT_LOGGING,
+  incidentLogPath,
+  loadGuardianConfig,
+  type GuardianConfig,
+  type GuardianLogging,
+} from "./config.js";
 import {
   buildIncidentRecord,
   guardAssistantMessage,
@@ -19,7 +25,6 @@ import {
 } from "./guardian.js";
 import { getProtectedPathBlock, hasPendingUserWork } from "./policies.js";
 
-const LOG_PATH = join("err", "guardian.jsonl");
 const RED = "\u001b[31m";
 const RESET_FOREGROUND = "\u001b[39m";
 
@@ -27,30 +32,49 @@ function red(text: string): string {
   return `${RED}${text}${RESET_FOREGROUND}`;
 }
 
-export async function appendIncident(cwd: string, incident: GuardianIncident): Promise<void> {
-  const directory = join(cwd, "err");
-  const path = join(cwd, LOG_PATH);
-  await mkdir(directory, { recursive: true });
+/**
+ * Append one forensic record. The path never depends on the session cwd, so opening an
+ * untrusted repository cannot leave an untracked log full of provider payloads inside it.
+ * Once an append would pass `logging.maxBytes` the current file moves to `<file>.1`: one
+ * generation of history is kept, anything older is dropped.
+ */
+export async function appendIncident(
+  incident: GuardianIncident,
+  logging: GuardianLogging = DEFAULT_LOGGING,
+): Promise<void> {
+  const path = incidentLogPath(logging);
+  if (path === null) return;
+
+  const line = `${JSON.stringify(incident)}\n`;
+  await mkdir(dirname(path), { recursive: true });
 
   let existed = true;
+  let size = 0;
   try {
-    await stat(path);
+    size = (await stat(path)).size;
   } catch {
     existed = false;
   }
+  if (existed && size + Buffer.byteLength(line) > logging.maxBytes) {
+    await rename(path, `${path}.1`).catch(() => {});
+    existed = false;
+  }
 
-  await appendFile(path, `${JSON.stringify(incident)}\n`, "utf8");
+  await appendFile(path, line, "utf8");
   if (!existed && process.platform !== "win32") {
     await chmod(path, 0o600).catch(() => {});
   }
 }
 
-function diagnostic(removed: number, logError?: unknown): string {
+function diagnostic(removed: number, incidentFile: string | null, logError?: unknown): string {
+  if (incidentFile === null) {
+    return `[opl-guardian] Dropped ${removed} malformed provider tool call(s); incident logging is off (logging.incidentFile: false).`;
+  }
   if (logError) {
     const detail = logError instanceof Error ? logError.message : String(logError);
-    return `[opl-guardian] Dropped malformed provider tool call(s), but could not write err/guardian.jsonl: ${detail}.`;
+    return `[opl-guardian] Dropped malformed provider tool call(s), but could not write ${incidentFile}: ${detail}.`;
   }
-  return `[opl-guardian] Dropped ${removed} malformed provider tool call(s). Details: err/guardian.jsonl.`;
+  return `[opl-guardian] Dropped ${removed} malformed provider tool call(s). Details: ${incidentFile}.`;
 }
 
 function appendDiagnostic(message: AssistantMessage, text: string, invalidOnly: boolean): AssistantMessage {
@@ -67,20 +91,20 @@ function appendDiagnostic(message: AssistantMessage, text: string, invalidOnly:
 
 export async function guardMessageEnd(
   message: AssistantMessage,
-  context: { cwd: string; sessionId: string },
+  context: { cwd: string; sessionId: string; logging?: GuardianLogging },
 ): Promise<{ message: AssistantMessage; diagnostic: string } | undefined> {
   const guarded = guardAssistantMessage(message);
   if (!guarded) return undefined;
 
   let logError: unknown;
   try {
-    await appendIncident(context.cwd, buildIncidentRecord(message, context, guarded.removedToolCalls));
+    await appendIncident(buildIncidentRecord(message, context, guarded.removedToolCalls), context.logging ?? DEFAULT_LOGGING);
   } catch (error) {
     logError = error;
   }
 
   const invalidOnly = !guarded.message.content.some((block) => block.type === "toolCall");
-  const notice = diagnostic(guarded.removedToolCalls.length, logError);
+  const notice = diagnostic(guarded.removedToolCalls.length, incidentLogPath(context.logging ?? DEFAULT_LOGGING), logError);
   return {
     message: appendDiagnostic(guarded.message, notice, invalidOnly),
     diagnostic: notice,
@@ -101,7 +125,16 @@ export function createToolCallHandler(config: GuardianConfig) {
     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;
+    else if (isToolCallEventType("bash", event) && typeof event.input.command === "string") {
+      toolPath = event.input.command;
+    } else if (isToolCallEventType("bash", event)) {
+      // The host types `command` as a string. A provider that sends an array or object here
+      // hands over something uninspectable, and coercing it would let ["rm","-rf"] read as
+      // "rm,-rf" to the matchers. Fail closed, the way a blank id or name does.
+      const reason = "[opl-guardian] Blocked a bash tool call whose command was not a string.";
+      if (ctx.hasUI) ctx.ui.notify(red(reason), "warning");
+      return { block: true, reason };
+    }
 
     if (toolPath !== undefined) {
       const blocked = getProtectedPathBlock(event.toolName, toolPath, config.protectedPaths.paths, ctx.cwd);
@@ -115,6 +148,7 @@ export function createToolCallHandler(config: GuardianConfig) {
     }
 
     if (!isToolCallEventType("bash", event) ||
+      typeof event.input.command !== "string" ||
       !config.permissionGate.patterns.some((pattern) => pattern.test(event.input.command))) return undefined;
 
     if (!ctx.hasUI) {
@@ -155,6 +189,7 @@ export function createMessageEndHandler(config: GuardianConfig) {
     const guarded = await guardMessageEnd(event.message, {
       cwd: ctx.cwd,
       sessionId: ctx.sessionManager.getSessionId(),
+      logging: config.logging,
     });
     if (!guarded) return undefined;
     ctx.ui?.notify(red(guarded.diagnostic), "warning");

package/extensions/opl-guardian/policies.ts

@@ -60,6 +60,43 @@ export function matchesProtectedPath(toolPath: string, entry: PathEntry, cwd: st
   return toolPath.split(/[\\/]/).some((part) => part === segment);
 }
 
+/**
+ * Split a shell command into the words a path could appear as. Quotes, command
+ * substitutions, redirections and separators are treated as boundaries, so
+ * `python -c 'open(".env")'` yields `.env` while `"process.env"` stays one word.
+ */
+function commandTokens(command: string): string[] {
+  const tokens: string[] = [];
+  for (const raw of command.split(/[\s'"`|&;()<>:,=]+/)) {
+    const token = raw.replace(/^[-+]+/, "").replace(/[,.;:]+$/, "");
+    if (token.length >= 2) tokens.push(token);
+  }
+  return tokens;
+}
+
+/**
+ * Does this command mention the protected path?
+ *
+ * Matching is per token and path-aware, so argument text no longer trips the
+ * rule (`grep "process.env" src` is not a read of `.env`), and tokens are
+ * resolved through symlinks the same way the read/write/edit rules are. It is
+ * still advisory for bash: a command that builds a path at run time
+ * (`x=.env; cat $x`, `cat .en""v`) cannot be recognised from text, and a
+ * `cd`-then-relative-path sequence resolves against the session cwd.
+ */
+export function bashCommandMentionsPath(command: string, entry: PathEntry, cwd: string): boolean {
+  for (const token of commandTokens(command)) {
+    if (matchesProtectedPath(token, entry, cwd)) return true;
+    const resolved = resolveConfiguredPath(token, cwd);
+    if (matchesResolvedPath(resolved, entry.path, cwd)) return true;
+    const physical = physicalPath(resolved);
+    if (physical && (matchesProtectedPath(physical, entry, cwd) || matchesResolvedPath(physical, entry.path, cwd))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export function hasPendingUserWork(entries: SessionEntry[]): boolean {
   let pending = false;
   for (const entry of entries) {
@@ -83,7 +120,10 @@ export function getProtectedPathBlock(
   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, " ");
+  let normalizedTool = toolPath;
+  if (operation !== "bash") {
+    normalizedTool = toolPath.replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, " ");
+  }
   if (operation !== "bash") {
     if (normalizedTool.startsWith("@")) normalizedTool = normalizedTool.slice(1);
     if (normalizedTool.startsWith("file://")) {
@@ -99,21 +139,17 @@ export function getProtectedPathBlock(
     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);
-      }
+    // Bash gets token/path matching; its `toolPath` is the whole command, so a
+    // substring test there would police argument text instead of file access.
+    const matches = operation === "bash"
+      ? bashCommandMentionsPath(toolPath, entry, cwd)
+      : matchesProtectedPath(normalizedTool, entry, cwd) || matchesProtectedPath(canonicalTool!, entry, cwd);
+    if (!matches && operation !== "bash" && isAbsoluteOrHomeRelative(entry.path)) {
+      const canonicalEntry = physicalPath(resolveConfiguredPath(entry.path, cwd));
+      if (!canonicalEntry) return { path: entry.path, operation, unresolved: true };
+      const matched = matchesResolvedPath(canonicalTool!, canonicalEntry, cwd);
+      if (!matched) continue;
+      return { path: entry.path, operation };
     }
 
     if (matches) return { path: entry.path, operation };