@openlines/opl-pi-sht 0.2.12 → 0.3.1

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 };

package/extensions/opl-init/README.md

@@ -9,13 +9,19 @@ Generates or refreshes a repository-specific `AGENTS.md` guide through `/init`.
 
 ## Extension features
 
-- Produces a deterministic repository guide with package commands and a file-type inventory, then refines it with **one** `ctx.modelRegistry.streamSimple()` call on the current model (pi >= 0.86.0). The refinement never enters the conversation: no synthetic user message, no turn in the transcript, no `write` tool needed, and read-only/chat/plan modes refine identically.
+- Produces a deterministic repository guide with package commands and a file-type inventory, then refines it with **one** `ctx.modelRegistry.streamSimple()` call on the current model at `reasoning: "minimal"` (pi >= 0.86.0). The refinement never enters the conversation: no synthetic user message, no turn in the transcript, no `write` tool needed, and read-only/chat/plan modes refine identically. `"minimal"` is the lowest thinking level pi-ai accepts; an earlier `{ reasoning: false }` read as *unset*, so the call silently paid the provider's default thinking level.
 - The model only sees a bounded evidence packet (the baseline guide, every `package.json`'s full scripts block, and the first ~2 KB of each root/workspace `README`/`CLAUDE.md`, hard 24 KB budget with an explicit truncation line). The crawl is the only explorer.
 - The extension owns the fingerprint marker: model output is stripped of fences and any `opl-init:fp` comment, and the exact marker is appended as the final line. A model can never corrupt or fake a "current" guide.
 - Refine failure (no model, no auth, provider error, empty output) writes the deterministic baseline and notifies `refine failed` - `/init` only fails to write if the write itself fails.
 - Mid-session `/init` waits for the agent to settle (`ctx.waitForIdle()`), recomputes the fingerprint, and only then crawls. It never steers or interrupts the task in flight.
-- Crawls to depth 3, ignores generated/dependency directories, caps directory listings at 40 entries, caps the rendered tree at 300 lines with explicit omission markers, and re-walks declared `pnpm-workspace.yaml`/Cargo members with their own depth-3 budget.
-- Fingerprints dirty tracked + untracked file **contents** (plus HEAD and a generator schema version), excluding the root `AGENTS.md` itself, so writing the guide never makes it immediately stale and re-editing an already-modified file is never read as "current".
+- Crawls to depth 3, ignores generated/dependency directories, caps directory listings at 40 entries and the rendered tree at 300 lines with explicit omission markers, and re-walks declared `pnpm-workspace.yaml`/Cargo members with their own depth-3 budget. Workspace globs escape every metacharacter except `*` and `?`, because real member patterns carry them (`packages/app(one`, `libs/c++/*`); an unescaped one threw `SyntaxError` and aborted the entire crawl. A glob that compiles to nothing is skipped, reported in `Crawl.skippedGlobs`, and named in a tree line so the skip is visible in the guide.
+- Fingerprints dirty tracked + untracked files (plus HEAD and a generator schema version), excluding the root `AGENTS.md` itself, so writing the guide never makes it immediately stale and re-editing an already-modified file is never read as "current". Content hashing is **budgeted** (`FP_LIMITS`: 2 MB per file, 32 MB total, 5,000 paths): past the per-file or total ceiling a file contributes `name|size|mtime` instead of its bytes, and past the path ceiling a path contributes its name plus `OVER_CAP`. Budget state is folded into the digest, so the fingerprint cannot oscillate. Without the ceilings a single 200 MB build artifact cost 143 ms and +200 MB of RSS on every `/init`.
+
+## User-owned operational notes
+
+`/init` preserves an existing `## Operational notes` section verbatim, including nested `###` subsections, whitespace and line endings. The section ends at the next level-1 or level-2 Markdown heading outside a fenced code block, or at the end of the document. The final `opl-init:fp` marker belongs to the extension, not the section. The preserved section is placed after the regenerated guide and before that marker, whether model refinement succeeds or falls back to the deterministic crawl. Other hand-edited sections are replaced; if the protected heading is absent, generation is unchanged.
+
+Use one section with that exact, case-sensitive title. Duplicate sections cancel the update, as does a detected file change during refinement; resolve duplicates or rerun `/init` after editing. This protects against `/init` updates only, not ordinary agent edits or other programs.
 
 ## Requirements
 
@@ -23,4 +29,6 @@ Refinement needs pi 0.86.0 or newer (`ctx.modelRegistry.streamSimple`, `ctx.relo
 
 ## Architecture
 
-`index.ts` owns crawling, fingerprinting, the evidence packet, the model call, output validation, and writing. Git repositories fingerprint `schema version + HEAD + sha256 of every dirty tracked and untracked file` (root `AGENTS.md` excluded); non-git repositories use sorted path/size/mtime tuples. `/init` writes the file itself and reloads the session context; the main agent is never enlisted.
+Every `git` call goes through one guard. A repository is attacker-chosen data and can declare programs of its own (`[diff "x"] textconv`, `core.fsmonitor`, `core.hooksPath`, or a system/user config naming a helper) that git runs while answering what looks like a read-only query. The guard passes `--no-pager`, `-c core.fsmonitor=false`, `-c core.hooksPath=`, `-c protocol.ext.allow=never`, `-c credential.helper=`, `GIT_CONFIG_NOSYSTEM`, `GIT_ATTR_NOSYSTEM`, `GIT_TERMINAL_PROMPT=0` and `GIT_OPTIONAL_LOCKS=0`, plus `--no-ext-diff --no-textconv` on diff-family subcommands. Probes still ask for name-only or porcelain output, because that is all a fingerprint needs. The block is duplicated in `opl-footer/git-status.ts` - installs are per-directory, so the two cannot share a module - and `tests/net-guard-parity.test.mjs` fails if the copies drift.
+
+`index.ts` owns crawling, fingerprinting, the evidence packet, the model call, output validation, and writing. Git repositories fingerprint `schema version + HEAD + a budgeted digest of dirty tracked and untracked files` (root `AGENTS.md` excluded, content replaced by `size|mtime` past the byte ceilings); non-git repositories use sorted path/size/mtime tuples. `gitOutput` caps captured output at 4 MB because every probe asks for path lists or a single value. `/init` writes the file itself and reloads the session context; the main agent is never enlisted.