pi-mono-all 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # pi-mono-all
 
+## 1.2.2
+
+### Patch Changes
+
+- Bundle `pi-mono-sentinel@1.11.0` with guardrails hardening, path-access grants, event emission, and internal simplifications.
+
 ## 1.2.1
 
 ### Patch Changes

package/node_modules/pi-mono-sentinel/.pi/extensions/sentinel.json

@@ -0,0 +1,7 @@
+{
+  "outputScanner": {
+    "readAllowedPaths": [
+      "/safe/example-doc.md"
+    ]
+  }
+}

package/node_modules/pi-mono-sentinel/CHANGELOG.md

@@ -1,5 +1,20 @@
 # pi-mono-sentinel
 
+## 1.11.0
+
+### Minor Changes
+
+### Enhanced: guardrails hardening
+
+- Added merged Sentinel configuration scopes: global (`~/.pi/agent/extensions/sentinel.json`), local (`.pi/extensions/sentinel.json`), and session memory.
+- Added optional path-access guard with allow/ask/block modes and file/directory grant persistence.
+- Added `sentinel:dangerous` and `sentinel:blocked` event emission from guards.
+- Added internal shell-aware bash command analysis with fallback matching.
+
+### Maintenance
+
+- Simplified Sentinel config persistence, path-access grants, event emission, and shell traversal internals without changing guard behavior.
+
 ## 1.10.2
 
 ### Patch Changes

package/node_modules/pi-mono-sentinel/README.md

@@ -9,6 +9,63 @@ It addresses cross-cutting security gaps that pure command-based guardrails miss
 - **Out-of-scope operations** — a raw `bash` command performs a system-level action (sudo, `curl | bash`, `brew install`, `rm -rf /Library/...`) or a `write`/`edit` targets a file outside the project root (shell config, system directory)
 - **Credential safety** — the LLM never hardcodes API keys or secrets in tool calls
 
+## Configuration
+
+Sentinel reads and merges optional JSON config from three scopes:
+
+1. Global: `$PI_CODING_AGENT_DIR/extensions/sentinel.json` or `~/.pi/agent/extensions/sentinel.json`
+2. Local/project: `.pi/extensions/sentinel.json` under the current working directory
+3. Memory: session-only grants written internally while Pi is running
+
+Merge priority is `memory > local > global > defaults`.
+
+```json
+{
+  "enabled": true,
+  "features": {
+    "outputScanner": true,
+    "executionTracker": true,
+    "permissionGate": true,
+    "pathAccess": false
+  },
+  "pathAccess": {
+    "mode": "ask",
+    "allowedPaths": []
+  },
+  "permissionGate": {
+    "requireConfirmation": true,
+    "allowedPatterns": [],
+    "autoDenyPatterns": []
+  },
+  "outputScanner": {
+    "readAllowedPaths": []
+  }
+}
+```
+
+All fields are optional. Path access is available but disabled by default to avoid surprising existing users.
+
+### Path access grants
+
+When `features.pathAccess` is enabled, Sentinel checks `read`, `write`, `edit`, and path-like `bash` arguments that point outside `ctx.cwd`.
+
+Modes:
+
+- `allow` — no outside-project restrictions
+- `ask` — prompt to allow once, allow file/directory for the session, allow file/directory always, or deny
+- `block` — block outside-project paths unless they match `pathAccess.allowedPaths`
+
+Allowed directory grants use a trailing slash, e.g. `/tmp/shared/`; exact file grants omit it.
+
+### Events
+
+Sentinel emits best-effort extension events for other extensions:
+
+- `sentinel:dangerous` when a guard detects risky content or behavior
+- `sentinel:blocked` when a guard blocks a tool call
+
+Payloads include `feature`, `toolName`, `input`, and either `description`/`labels` or `reason`/`userDenied`.
+
 ## Guards
 
 ### 1. output-scanner — secret detection on read
@@ -41,6 +98,8 @@ If the target file was modified after the tracked write, it is re-read and re-sc
 
 Where `execution-tracker` only fires for _session-written_ scripts, `permission-gate` intercepts every `bash` command and every `write` / `edit` and matches them against a fixed set of risk classes. It runs in addition to the other two guards.
 
+Bash analysis uses Sentinel's small internal shell parser for quotes, redirects, pipelines, and command boundaries, with regex fallbacks when parsing fails.
+
 **Bash risk classes**
 
 | Risk class                | Example                                            |

package/node_modules/pi-mono-sentinel/__tests__/config.test.ts

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, test } from "node:test";
+
+import { SentinelConfigLoader } from "../config.ts";
+
+describe("SentinelConfigLoader", () => {
+	let agentDir: string;
+	let cwd: string;
+	const originalAgentDir = process.env.PI_CODING_AGENT_DIR;
+
+	beforeEach(() => {
+		agentDir = mkdtempSync(join(tmpdir(), "sentinel-config-agent-"));
+		cwd = mkdtempSync(join(tmpdir(), "sentinel-config-cwd-"));
+		process.env.PI_CODING_AGENT_DIR = agentDir;
+	});
+
+	afterEach(() => {
+		if (originalAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = originalAgentDir;
+		rmSync(agentDir, { recursive: true, force: true });
+		rmSync(cwd, { recursive: true, force: true });
+	});
+
+	test("uses defaults when no config files exist", () => {
+		const loader = new SentinelConfigLoader();
+		loader.load(cwd);
+		const config = loader.getConfig();
+		assert.equal(config.enabled, true);
+		assert.equal(config.features.outputScanner, true);
+		assert.equal(config.features.pathAccess, false);
+		assert.equal(config.pathAccess.mode, "ask");
+	});
+
+	test("merges global, local, and memory with expected precedence", () => {
+		const loader = new SentinelConfigLoader();
+		mkdirSync(join(agentDir, "extensions"), { recursive: true });
+		writeFileSync(loader.getConfigPath("global"), JSON.stringify({ pathAccess: { allowedPaths: ["/global"] } }), { flag: "w" });
+		loader.load(cwd);
+		mkdirSync(join(cwd, ".pi", "extensions"), { recursive: true });
+		writeFileSync(loader.getConfigPath("local"), JSON.stringify({ features: { pathAccess: true }, pathAccess: { allowedPaths: ["/local"] } }), { flag: "w" });
+		loader.load(cwd);
+		loader.save("memory", { pathAccess: { mode: "block", allowedPaths: ["/memory"] } });
+		const config = loader.getConfig();
+		assert.equal(config.features.pathAccess, true);
+		assert.equal(config.pathAccess.mode, "block");
+		assert.deepEqual(config.pathAccess.allowedPaths, ["/memory"]);
+	});
+
+	test("save writes global and local config files", () => {
+		const loader = new SentinelConfigLoader();
+		loader.load(cwd);
+		loader.save("global", { enabled: false });
+		loader.save("local", { features: { pathAccess: true } });
+		assert.deepEqual(loader.getRawConfig("global"), { enabled: false });
+		assert.deepEqual(loader.getRawConfig("local"), { features: { pathAccess: true } });
+	});
+});

package/node_modules/pi-mono-sentinel/__tests__/events.test.ts

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+
+import { emitBlocked, emitDangerous } from "../events.ts";
+
+describe("sentinel events", () => {
+	test("emits blocked and dangerous events", () => {
+		const emitted: Array<{ name: string; payload: unknown }> = [];
+		const pi = {
+			events: {
+				emit(name: string, payload: unknown) {
+					emitted.push({ name, payload });
+				},
+			},
+		};
+
+		emitDangerous(pi as never, {
+			feature: "permissionGate",
+			toolName: "bash",
+			input: { command: "sudo true" },
+			description: "danger",
+			labels: ["privilege-escalation"],
+		});
+		emitBlocked(pi as never, {
+			feature: "permissionGate",
+			toolName: "bash",
+			input: { command: "sudo true" },
+			reason: "blocked",
+		});
+
+		assert.equal(emitted[0].name, "sentinel:dangerous");
+		assert.equal(emitted[1].name, "sentinel:blocked");
+	});
+
+	test("does not throw when event emitter is unavailable", () => {
+		assert.doesNotThrow(() =>
+			emitBlocked({} as never, {
+				feature: "pathAccess",
+				toolName: "read",
+				input: {},
+				reason: "blocked",
+			}),
+		);
+	});
+});

package/node_modules/pi-mono-sentinel/__tests__/path-access.test.ts

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, test } from "node:test";
+
+import { configLoader } from "../config.ts";
+import {
+	checkPathAccess,
+	directoryGrantFor,
+	isInsideCwd,
+	isPathAllowed,
+	pathAccessGrantForChoice,
+	toStoragePath,
+} from "../path-access.ts";
+
+const CWD = "/tmp/sentinel-project";
+
+describe("path-access helpers", () => {
+	test("allows paths inside cwd", () => {
+		assert.equal(isInsideCwd("/tmp/sentinel-project/src/index.ts", CWD), true);
+		assert.equal(checkPathAccess("/tmp/sentinel-project/src/index.ts", CWD, []).allowed, true);
+	});
+
+	test("detects paths outside cwd", () => {
+		const result = checkPathAccess("/tmp/other/file.txt", CWD, []);
+		assert.equal(result.allowed, false);
+	});
+
+	test("allows exact file grants", () => {
+		assert.equal(isPathAllowed("/tmp/other/file.txt", ["/tmp/other/file.txt"], CWD), true);
+		assert.equal(isPathAllowed("/tmp/other/else.txt", ["/tmp/other/file.txt"], CWD), false);
+	});
+
+	test("allows directory grants with trailing slash", () => {
+		assert.equal(isPathAllowed("/tmp/other/file.txt", ["/tmp/other/"], CWD), true);
+		assert.equal(isPathAllowed("/tmp/other/nested/file.txt", ["/tmp/other/"], CWD), true);
+		assert.equal(isPathAllowed("/tmp/otherness/file.txt", ["/tmp/other/"], CWD), false);
+	});
+
+	test("formats storage paths", () => {
+		assert.equal(toStoragePath("/tmp/other", true), "/tmp/other/");
+		assert.equal(directoryGrantFor("/tmp/other/file.txt"), "/tmp/other/");
+	});
+
+	test("derives and persists selected path-access grants with the correct scope and target", () => {
+		const cwd = mkdtempSync(join(tmpdir(), "sentinel-path-access-cwd-"));
+		try {
+			configLoader.load(cwd);
+			configLoader.save("memory", { features: { pathAccess: true }, pathAccess: { mode: "ask", allowedPaths: [] } });
+
+			const sessionDirectoryGrant = pathAccessGrantForChoice("allow_directory_session", "/tmp/outside-dir/file.txt", cwd);
+			assert.deepEqual(sessionDirectoryGrant, {
+				grant: "/tmp/outside-dir/",
+				broadCheckPath: "/tmp/outside-dir",
+				scope: "memory",
+				directory: true,
+			});
+			configLoader.addAllowedPath(sessionDirectoryGrant.scope, sessionDirectoryGrant.grant);
+			assert.ok(configLoader.getConfig().pathAccess.allowedPaths.includes("/tmp/outside-dir/"));
+
+			const localFileGrant = pathAccessGrantForChoice("allow_file_always", "/tmp/outside-file.txt", cwd);
+			assert.deepEqual(localFileGrant, {
+				grant: "/tmp/outside-file.txt",
+				broadCheckPath: "/tmp/outside-file.txt",
+				scope: "local",
+				directory: false,
+			});
+			configLoader.addAllowedPath(localFileGrant.scope, localFileGrant.grant);
+			assert.ok(configLoader.getRawConfig("local")?.pathAccess?.allowedPaths?.includes("/tmp/outside-file.txt"));
+		} finally {
+			rmSync(cwd, { recursive: true, force: true });
+		}
+	});
+});

package/node_modules/pi-mono-sentinel/__tests__/permissions.test.ts

@@ -118,6 +118,10 @@ describe("classifyBashCommand", () => {
 		assert.ok(matched.includes("remote-pipe-exec"));
 	});
 
+	test("does NOT flag dangerous words inside quoted strings", () => {
+		assert.deepEqual(classifyBashCommand('echo "sudo rm -rf /Library"'), []);
+	});
+
 	test("does NOT flag safe commands", () => {
 		assert.deepEqual(classifyBashCommand("echo hello"), []);
 		assert.deepEqual(classifyBashCommand("ls -la"), []);

package/node_modules/pi-mono-sentinel/config.ts

@@ -0,0 +1,193 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type SentinelConfigScope = "global" | "local" | "memory";
+export type SentinelPathAccessMode = "allow" | "ask" | "block";
+
+export interface SentinelConfig {
+	enabled?: boolean;
+	features?: {
+		outputScanner?: boolean;
+		executionTracker?: boolean;
+		permissionGate?: boolean;
+		pathAccess?: boolean;
+	};
+	pathAccess?: {
+		mode?: SentinelPathAccessMode;
+		allowedPaths?: string[];
+	};
+	permissionGate?: {
+		requireConfirmation?: boolean;
+		allowedPatterns?: string[];
+		autoDenyPatterns?: string[];
+	};
+	outputScanner?: {
+		readAllowedPaths?: string[];
+	};
+}
+
+export interface ResolvedSentinelConfig {
+	enabled: boolean;
+	features: {
+		outputScanner: boolean;
+		executionTracker: boolean;
+		permissionGate: boolean;
+		pathAccess: boolean;
+	};
+	pathAccess: {
+		mode: SentinelPathAccessMode;
+		allowedPaths: string[];
+	};
+	permissionGate: {
+		requireConfirmation: boolean;
+		allowedPatterns: string[];
+		autoDenyPatterns: string[];
+	};
+	outputScanner: {
+		readAllowedPaths: string[];
+	};
+}
+
+export const DEFAULT_SENTINEL_CONFIG: ResolvedSentinelConfig = {
+	enabled: true,
+	features: {
+		outputScanner: true,
+		executionTracker: true,
+		permissionGate: true,
+		pathAccess: false,
+	},
+	pathAccess: {
+		mode: "ask",
+		allowedPaths: [],
+	},
+	permissionGate: {
+		requireConfirmation: true,
+		allowedPatterns: [],
+		autoDenyPatterns: [],
+	},
+	outputScanner: {
+		readAllowedPaths: [],
+	},
+};
+
+export function getAgentDir(): string {
+	const envDir = process.env.PI_CODING_AGENT_DIR;
+	if (!envDir) return join(homedir(), ".pi", "agent");
+	if (envDir === "~") return homedir();
+	if (envDir.startsWith("~/")) return join(homedir(), envDir.slice(2));
+	return envDir;
+}
+
+function readJson(path: string): SentinelConfig | undefined {
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")) as SentinelConfig;
+	} catch {
+		return undefined;
+	}
+}
+
+function writeJson(path: string, value: SentinelConfig): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function mergeConfig<T>(base: T, override?: SentinelConfig | Record<string, unknown>): T {
+	if (!override) return structuredClone(base);
+	const result = structuredClone(base) as Record<string, unknown>;
+	for (const [key, value] of Object.entries(override)) {
+		if (value === undefined) continue;
+		const existing = result[key];
+		if (isPlainObject(existing) && isPlainObject(value)) {
+			result[key] = mergeConfig(existing, value);
+		} else if (Array.isArray(value)) {
+			result[key] = [...value];
+		} else {
+			result[key] = value;
+		}
+	}
+	return result as T;
+}
+
+function dedupe(values: string[]): string[] {
+	return [...new Set(values.filter((v) => typeof v === "string" && v.length > 0))];
+}
+
+export class SentinelConfigLoader {
+	private globalConfig: SentinelConfig | undefined;
+	private localConfig: SentinelConfig | undefined;
+	private memoryConfig: SentinelConfig = {};
+	private resolvedConfig: ResolvedSentinelConfig | undefined;
+	private localCwd = process.cwd();
+
+	load(cwd = process.cwd()): void {
+		this.localCwd = cwd;
+		this.globalConfig = readJson(this.getConfigPath("global"));
+		this.localConfig = readJson(this.getConfigPath("local"));
+		this.resolvedConfig = undefined;
+	}
+
+	getConfig(): ResolvedSentinelConfig {
+		if (this.resolvedConfig) return this.resolvedConfig;
+		let resolved = structuredClone(DEFAULT_SENTINEL_CONFIG) as ResolvedSentinelConfig;
+		resolved = mergeConfig(resolved, this.globalConfig);
+		resolved = mergeConfig(resolved, this.localConfig);
+		resolved = mergeConfig(resolved, this.memoryConfig);
+		resolved.pathAccess.allowedPaths = dedupe(resolved.pathAccess.allowedPaths);
+		resolved.permissionGate.allowedPatterns = dedupe(resolved.permissionGate.allowedPatterns);
+		resolved.permissionGate.autoDenyPatterns = dedupe(resolved.permissionGate.autoDenyPatterns);
+		resolved.outputScanner.readAllowedPaths = dedupe(resolved.outputScanner.readAllowedPaths);
+		this.resolvedConfig = resolved;
+		return resolved;
+	}
+
+	getRawConfig(scope: SentinelConfigScope): SentinelConfig | undefined {
+		return scope === "global" ? this.globalConfig : scope === "local" ? this.localConfig : this.memoryConfig;
+	}
+
+	getConfigPath(scope: Exclude<SentinelConfigScope, "memory">): string {
+		return scope === "global"
+			? join(getAgentDir(), "extensions", "sentinel.json")
+			: join(this.localCwd, ".pi", "extensions", "sentinel.json");
+	}
+
+	save(scope: SentinelConfigScope, partial: SentinelConfig): void {
+		if (scope === "memory") {
+			this.memoryConfig = mergeConfig(this.memoryConfig, partial);
+			this.resolvedConfig = undefined;
+			return;
+		}
+
+		const current = scope === "global" ? (this.globalConfig ?? {}) : (this.localConfig ?? {});
+		const next = mergeConfig(current, partial);
+		writeJson(this.getConfigPath(scope), next);
+		if (scope === "global") this.globalConfig = next;
+		else this.localConfig = next;
+		this.resolvedConfig = undefined;
+	}
+
+	private addListValue(scope: SentinelConfigScope, path: string, list: "allowedPaths" | "readAllowedPaths"): void {
+		const raw = this.getRawConfig(scope);
+		const current = list === "allowedPaths"
+			? raw?.pathAccess?.allowedPaths ?? []
+			: raw?.outputScanner?.readAllowedPaths ?? [];
+		const values = dedupe([...current, path]);
+		this.save(scope, list === "allowedPaths"
+			? { pathAccess: { allowedPaths: values } }
+			: { outputScanner: { readAllowedPaths: values } });
+	}
+
+	addAllowedPath(scope: SentinelConfigScope, path: string): void {
+		this.addListValue(scope, path, "allowedPaths");
+	}
+
+	addReadAllowedPath(scope: SentinelConfigScope, path: string): void {
+		this.addListValue(scope, path, "readAllowedPaths");
+	}
+}
+
+export const configLoader = new SentinelConfigLoader();

package/node_modules/pi-mono-sentinel/events.ts

@@ -0,0 +1,46 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type SentinelFeature =
+	| "outputScanner"
+	| "executionTracker"
+	| "permissionGate"
+	| "pathAccess";
+
+export interface SentinelBlockedEvent {
+	feature: SentinelFeature;
+	toolName: string;
+	input: Record<string, unknown>;
+	reason: string;
+	userDenied?: boolean;
+}
+
+export interface SentinelDangerousEvent {
+	feature: SentinelFeature;
+	toolName: string;
+	input: Record<string, unknown>;
+	description: string;
+	labels?: string[];
+}
+
+export type SentinelBlockResult = { block: true; reason: string };
+
+function emitSentinelEvent(pi: ExtensionAPI, name: "sentinel:blocked" | "sentinel:dangerous", event: unknown): void {
+	try {
+		pi.events?.emit?.(name, event);
+	} catch {
+		// Event emission is best-effort and must never affect guard decisions.
+	}
+}
+
+export function emitBlocked(pi: ExtensionAPI, event: SentinelBlockedEvent): void {
+	emitSentinelEvent(pi, "sentinel:blocked", event);
+}
+
+export function blockToolCall(pi: ExtensionAPI, event: SentinelBlockedEvent, reason = event.reason): SentinelBlockResult {
+	emitBlocked(pi, event);
+	return { block: true, reason };
+}
+
+export function emitDangerous(pi: ExtensionAPI, event: SentinelDangerousEvent): void {
+	emitSentinelEvent(pi, "sentinel:dangerous", event);
+}

package/node_modules/pi-mono-sentinel/guards/execution-tracker.ts

@@ -20,6 +20,7 @@ import { resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
 
+import { blockToolCall, emitDangerous } from "../events.js";
 import type { SentinelSession } from "../session.js";
 import type { DangerousPattern, WriteEntry } from "../types.js";
 
@@ -221,6 +222,14 @@ export function registerExecutionTracker(
 				continue;
 			}
 
+			emitDangerous(pi, {
+				feature: "executionTracker",
+				toolName: "bash",
+				input: event.input,
+				description: "Bash command executes a session-written file with dangerous content.",
+				labels: currentPatterns,
+			});
+
 			// Dangerous content confirmed — escalate
 			const message = [
 				`About to execute a file written earlier in this session:`,
@@ -239,12 +248,10 @@ export function registerExecutionTracker(
 			}
 
 			// No UI or user denied — block
-			return {
-				block: true,
-				reason:
-					`[sentinel] Blocked: bash executes ${scriptPath}, written this session ` +
-					`with dangerous patterns: ${currentPatterns.join(", ")}.`,
-			};
+			const reason =
+				`[sentinel] Blocked: bash executes ${scriptPath}, written this session ` +
+				`with dangerous patterns: ${currentPatterns.join(", ")}.`;
+			return blockToolCall(pi, { feature: "executionTracker", toolName: "bash", input: event.input, reason, userDenied: ctx.hasUI });
 		}
 	});
 }