pi-mono-sentinel 1.6.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# pi-mono-sentinel
+
+## 1.6.0
+
+### Minor Changes
+
+Initial release of sentinel extension, replacing the previous `grep` extension with a security-focused monitoring and guarding system for sensitive operations.

package/LICENCE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Emanuel Casco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/guards/execution-tracker.ts

@@ -0,0 +1,281 @@
+/**
+ * execution-tracker — Gap 3: Indirect execution attack mitigation.
+ *
+ * Two hooks working together:
+ *
+ * 1. **Write-time tracking** (`tool_call` on `write` / `edit`):
+ *    Records every file written during the session and scans the content
+ *    for dangerous execution patterns (curl|bash, eval, exfiltration, etc.).
+ *    Does NOT block — only records metadata in the session write registry.
+ *
+ * 2. **Execution-time correlation** (`tool_call` on `bash`):
+ *    Extracts script paths from bash commands and checks them against the
+ *    session write registry. If a script was written this session and
+ *    contains dangerous patterns, asks/denies before allowing execution.
+ */
+
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
+
+import type { SentinelSession } from "../session.js";
+import type { DangerousPattern, WriteEntry } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Dangerous content patterns (for scripts)
+// ---------------------------------------------------------------------------
+
+const DANGEROUS_PATTERNS: readonly DangerousPattern[] = [
+	{
+		label: "curl-pipe-exec",
+		pattern: /curl\s.*\|\s*(?:bash|sh|zsh)/,
+	},
+	{
+		label: "wget-pipe-exec",
+		pattern: /wget\s.*\|\s*(?:bash|sh|zsh)/,
+	},
+	{
+		label: "eval-subshell",
+		pattern: /eval\s+["'$]/,
+	},
+	{
+		label: "network-exfil",
+		pattern: /curl\s.*(?:-X\s*POST|--data\b|-d\s)/,
+	},
+	{
+		label: "rm-recursive",
+		pattern: /rm\s+-[a-zA-Z]*r[a-zA-Z]*f/,
+	},
+	{
+		label: "privilege-escalation",
+		pattern: /(?:chmod\s+777|sudo\s)/,
+	},
+	{
+		label: "persistence",
+		pattern: /(?:crontab|systemctl\s+enable|launchctl)/,
+	},
+];
+
+// ---------------------------------------------------------------------------
+// Script execution path extraction
+// ---------------------------------------------------------------------------
+
+const EXEC_PATTERNS: readonly RegExp[] = [
+	/\b(?:bash|sh|zsh|dash)\s+(\S+)/,
+	/\b(?:node|python3?|ruby|perl|tsx?)\s+(\S+)/,
+	/\bsource\s+(\S+)/,
+	/^\.\s+(\S+)/,
+	/^\.\/(\S+)/,
+];
+
+/** Extract potential script file paths from a bash command. */
+function extractScriptPaths(command: string): string[] {
+	const paths: string[] = [];
+	for (const pattern of EXEC_PATTERNS) {
+		const match = pattern.exec(command);
+		if (match?.[1]) {
+			const target = match[1];
+			// Skip flags
+			if (!target.startsWith("-")) {
+				paths.push(target);
+			}
+		}
+	}
+	return paths;
+}
+
+// ---------------------------------------------------------------------------
+// Content scanning
+// ---------------------------------------------------------------------------
+
+/** Scan content for dangerous execution patterns. Returns matched labels. */
+function scanForDangerousContent(content: string): string[] {
+	const matched: string[] = [];
+	for (const { label, pattern } of DANGEROUS_PATTERNS) {
+		if (pattern.test(content)) {
+			matched.push(label);
+		}
+	}
+	return matched;
+}
+
+// ---------------------------------------------------------------------------
+// Guard registration
+// ---------------------------------------------------------------------------
+
+export function registerExecutionTracker(
+	pi: ExtensionAPI,
+	session: SentinelSession,
+): void {
+	// -----------------------------------------------------------------------
+	// 4a. Write-time tracking — record writes and flag dangerous content
+	// -----------------------------------------------------------------------
+
+	// Track `write` tool calls
+	pi.on("tool_call", async (event, ctx) => {
+		if (!isToolCallEventType("write", event)) return;
+
+		const rawPath = event.input.path;
+		const content = event.input.content;
+		if (!rawPath || typeof content !== "string") return;
+
+		const absolutePath = resolve(ctx.cwd, rawPath);
+		const dangerousPatterns = scanForDangerousContent(content);
+
+		session.registerWrite({
+			path: absolutePath,
+			timestamp: Date.now(),
+			hasDangerousContent: dangerousPatterns.length > 0,
+			dangerousPatterns,
+		});
+
+		if (dangerousPatterns.length > 0) {
+			ctx.ui.notify(
+				`[sentinel] Write tracked: ${rawPath} flagged (${dangerousPatterns.join(", ")})`,
+				"warning",
+			);
+		}
+	});
+
+	// Track `edit` tool calls
+	pi.on("tool_call", async (event, ctx) => {
+		if (!isToolCallEventType("edit", event)) return;
+
+		const rawPath = event.input.path;
+		const edits = event.input.edits as
+			| Array<{ oldText: string; newText: string }>
+			| undefined;
+		if (!rawPath || !edits?.length) return;
+
+		const absolutePath = resolve(ctx.cwd, rawPath);
+		const allNewText = edits.map((e) => e.newText).join("\n");
+		const dangerousPatterns = scanForDangerousContent(allNewText);
+
+		// For edits, merge with existing entry if present
+		const existing = session.getWrite(absolutePath);
+		const mergedPatterns = existing
+			? [...new Set([...existing.dangerousPatterns, ...dangerousPatterns])]
+			: dangerousPatterns;
+
+		session.registerWrite({
+			path: absolutePath,
+			timestamp: Date.now(),
+			hasDangerousContent: mergedPatterns.length > 0,
+			dangerousPatterns: mergedPatterns,
+		});
+
+		if (dangerousPatterns.length > 0) {
+			ctx.ui.notify(
+				`[sentinel] Edit tracked: ${rawPath} flagged (${dangerousPatterns.join(", ")})`,
+				"warning",
+			);
+		}
+	});
+
+	// -----------------------------------------------------------------------
+	// 4b. Execution-time correlation — check bash against write registry
+	// -----------------------------------------------------------------------
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (!isToolCallEventType("bash", event)) return;
+
+		const command = event.input.command ?? "";
+		const scriptPaths = extractScriptPaths(command);
+		if (scriptPaths.length === 0) return;
+
+		for (const scriptPath of scriptPaths) {
+			const absolutePath = resolve(ctx.cwd, scriptPath);
+			const writeEntry = session.getWrite(absolutePath);
+
+			// Not written this session — skip
+			if (!writeEntry) continue;
+
+			// Written this session but no dangerous content — notify only
+			if (!writeEntry.hasDangerousContent) {
+				ctx.ui.notify(
+					`[sentinel] Executing session-written file: ${scriptPath}`,
+					"info",
+				);
+				continue;
+			}
+
+			// Re-verify: file may have been modified externally since we tracked the write
+			const currentPatterns = await rescanFileIfChanged(
+				absolutePath,
+				writeEntry,
+			);
+
+			// File was modified and no longer dangerous
+			if (currentPatterns.length === 0) {
+				session.registerWrite({
+					...writeEntry,
+					hasDangerousContent: false,
+					dangerousPatterns: [],
+				});
+				ctx.ui.notify(
+					`[sentinel] File ${scriptPath} was modified — no longer flagged`,
+					"info",
+				);
+				continue;
+			}
+
+			// Dangerous content confirmed — escalate
+			const message = [
+				`About to execute a file written earlier in this session:`,
+				`  Path: ${scriptPath}`,
+				`  Flagged patterns: ${currentPatterns.join(", ")}`,
+				"",
+				"Allow execution?",
+			].join("\n");
+
+			if (ctx.hasUI) {
+				const allowed = await ctx.ui.confirm(
+					"[sentinel] Dangerous script execution",
+					message,
+				);
+				if (allowed) continue;
+			}
+
+			// No UI or user denied — block
+			return {
+				block: true,
+				reason:
+					`[sentinel] Blocked: bash executes ${scriptPath}, written this session ` +
+					`with dangerous patterns: ${currentPatterns.join(", ")}.`,
+			};
+		}
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Re-read and re-scan a file to verify dangerous content is still present.
+ * Handles the edge case where the file was modified externally between
+ * write-time tracking and execution-time correlation.
+ */
+async function rescanFileIfChanged(
+	absolutePath: string,
+	writeEntry: WriteEntry,
+): Promise<string[]> {
+	try {
+		const fileStat = await stat(absolutePath);
+
+		// If the file was modified after we tracked the write, re-scan
+		if (fileStat.mtimeMs > writeEntry.timestamp) {
+			const content = await readFile(absolutePath, "utf-8");
+			return scanForDangerousContent(content);
+		}
+
+		// File unchanged — trust the original scan
+		return writeEntry.dangerousPatterns;
+	} catch {
+		// File gone or unreadable — no longer dangerous
+		return [];
+	}
+}
+

package/guards/output-scanner.ts

@@ -0,0 +1,211 @@
+/**
+ * output-scanner — Gap 2: Content-in-location attack mitigation.
+ *
+ * Pre-reads files before `read` tool calls execute and scans for secret
+ * patterns. If secrets are found, asks the user before allowing the read.
+ *
+ * Since `tool_result` is read-only in the pi extension API, we intercept
+ * at `tool_call` time — read the file ourselves, scan it, and make an
+ * ASK/DENY decision before the actual read proceeds.
+ *
+ * Also intercepts `bash` commands that read files (cat, head, tail, less)
+ * and pre-scans the target files.
+ */
+
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
+
+import type { SentinelSession } from "../session.js";
+import type { ScanMatch } from "../types.js";
+import {
+	isBinaryContent,
+	MAX_SCAN_BYTES,
+	scanForSecrets,
+} from "../patterns/secrets.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Format scan matches into a human-readable confirmation message. */
+function formatConfirmMessage(matches: ScanMatch[]): string {
+	const lines = matches.map(
+		(m) => `  - ${m.label} (line ${m.line}): ${m.snippet}`,
+	);
+	return [
+		"File may contain secrets:",
+		...lines,
+		"",
+		"Allow this read?",
+	].join("\n");
+}
+
+/**
+ * Extract file paths from bash commands that read file content.
+ * Targets: cat, head, tail, less, more.
+ */
+function extractReadTargets(command: string): string[] {
+	const pattern = /\b(?:cat|head|tail|less|more)\s+([^\s|;&]+)/g;
+	const paths: string[] = [];
+	let match: RegExpExecArray | null;
+	while ((match = pattern.exec(command)) !== null) {
+		const target = match[1];
+		// Skip flags (start with -)
+		if (!target.startsWith("-")) {
+			paths.push(target);
+		}
+	}
+	return paths;
+}
+
+/**
+ * Pre-read a file and scan for secrets. Uses the session scan cache to
+ * avoid redundant filesystem reads on unchanged files.
+ *
+ * Returns the scan matches, or an empty array if the file is binary,
+ * too large, or unreadable.
+ */
+async function scanFile(
+	absolutePath: string,
+	session: SentinelSession,
+): Promise<ScanMatch[]> {
+	try {
+		const fileStat = await stat(absolutePath);
+
+		// Check cache first
+		const cached = session.getCachedScan(absolutePath, fileStat.mtimeMs);
+		if (cached) return cached.matches;
+
+		// Skip files larger than scan limit
+		if (fileStat.size > MAX_SCAN_BYTES) return [];
+
+		// Skip non-files (directories, symlinks, etc.)
+		if (!fileStat.isFile()) return [];
+
+		const content = await readFile(absolutePath, "utf-8");
+
+		// Skip binary files
+		if (isBinaryContent(content)) {
+			session.cacheScan(absolutePath, fileStat.mtimeMs, {
+				hasSecrets: false,
+				matches: [],
+			});
+			return [];
+		}
+
+		const result = scanForSecrets(content);
+		session.cacheScan(absolutePath, fileStat.mtimeMs, result);
+		return result.matches;
+	} catch {
+		// File unreadable (permissions, doesn't exist, etc.) — let the tool handle the error
+		return [];
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Guard registration
+// ---------------------------------------------------------------------------
+
+export function registerOutputScanner(
+	pi: ExtensionAPI,
+	session: SentinelSession,
+): void {
+	// -----------------------------------------------------------------------
+	// Intercept `read` tool calls
+	// -----------------------------------------------------------------------
+	pi.on("tool_call", async (event, ctx) => {
+		if (!isToolCallEventType("read", event)) return;
+
+		const rawPath = event.input.path;
+		if (!rawPath) return;
+
+		const absolutePath = resolve(
+			ctx.cwd,
+			rawPath.startsWith("@") ? rawPath.slice(1) : rawPath,
+		);
+
+		const matches = await scanFile(absolutePath, session);
+		if (matches.length === 0) return;
+
+		// Secrets found — escalate
+		if (ctx.hasUI) {
+			const allowed = await ctx.ui.confirm(
+				"[sentinel] Secret detected",
+				formatConfirmMessage(matches),
+			);
+			if (allowed) return; // User approved — let the read proceed
+		}
+
+		// No UI or user denied — block
+		return {
+			block: true,
+			reason:
+				`[sentinel] Blocked: file contains ${matches.length} potential secret(s). ` +
+				matches.map((m) => m.label).join(", ") +
+				".",
+		};
+	});
+
+	// -----------------------------------------------------------------------
+	// Intercept `bash` commands that read files (cat, head, tail, less)
+	// -----------------------------------------------------------------------
+	pi.on("tool_call", async (event, ctx) => {
+		if (!isToolCallEventType("bash", event)) return;
+
+		const command = event.input.command ?? "";
+		const targets = extractReadTargets(command);
+		if (targets.length === 0) return;
+
+		// Scan all targeted files
+		const allMatches: Array<{ path: string; matches: ScanMatch[] }> = [];
+		for (const target of targets) {
+			const absolutePath = resolve(ctx.cwd, target);
+			const matches = await scanFile(absolutePath, session);
+			if (matches.length > 0) {
+				allMatches.push({ path: target, matches });
+			}
+		}
+
+		if (allMatches.length === 0) return;
+
+		// Build a combined confirmation message
+		const message = allMatches
+			.flatMap(({ path, matches }) =>
+				matches.map(
+					(m) => `  - ${m.label} in ${path} (line ${m.line}): ${m.snippet}`,
+				),
+			)
+			.join("\n");
+
+		if (ctx.hasUI) {
+			const allowed = await ctx.ui.confirm(
+				"[sentinel] Secret detected in bash target",
+				`Command reads file(s) that may contain secrets:\n${message}\n\nAllow execution?`,
+			);
+			if (allowed) return;
+		}
+
+		const totalMatches = allMatches.reduce(
+			(sum, entry) => sum + entry.matches.length,
+			0,
+		);
+		return {
+			block: true,
+			reason:
+				`[sentinel] Blocked: bash command reads file(s) with ${totalMatches} potential secret(s).`,
+		};
+	});
+
+	// -----------------------------------------------------------------------
+	// Invalidate scan cache when context-guard reports a file modification
+	// -----------------------------------------------------------------------
+	pi.events.on("context-guard:file-modified", (data: unknown) => {
+		const event = data as { path?: string } | undefined;
+		if (event?.path) {
+			session.invalidateScanCache(resolve(event.path));
+		}
+	});
+}

package/index.ts

@@ -0,0 +1,34 @@
+/**
+ * sentinel — content-aware security guard for pi coding agents.
+ *
+ * Two guards addressing cross-cutting security gaps:
+ *
+ * 1. **output-scanner** (Gap 2 — content-in-location):
+ *    Pre-reads files before `read` tool calls and scans for secret patterns.
+ *    Asks the user before allowing reads that contain credentials.
+ *
+ * 2. **execution-tracker** (Gap 3 — indirect execution):
+ *    Tracks files written during the session and scans for dangerous patterns.
+ *    When `bash` executes a file written this session, correlates the write
+ *    with the execution and asks/denies based on flagged content.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { SentinelSession } from "./session.js";
+import { registerOutputScanner } from "./guards/output-scanner.js";
+import { registerExecutionTracker } from "./guards/execution-tracker.js";
+
+export default function (pi: ExtensionAPI): void {
+	const session = new SentinelSession();
+
+	pi.on("session_start", async () => {
+		session.reset();
+	});
+
+	// Gap 2: scan file content before reads
+	registerOutputScanner(pi, session);
+
+	// Gap 3: track writes + correlate with bash execution
+	registerExecutionTracker(pi, session);
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "pi-mono-sentinel",
+  "version": "1.6.0",
+  "description": "Pi extension that guards against content-based secret leaks and indirect script execution",
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emanuelcasco/pi-mono-extensions.git",
+    "directory": "extensions/sentinel"
+  }
+}

package/patterns/secrets.ts

@@ -0,0 +1,143 @@
+import type { ScanMatch, ScanResult } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Known secret patterns
+// ---------------------------------------------------------------------------
+
+type SecretPattern = {
+	label: string;
+	regex: RegExp;
+};
+
+const SECRET_PATTERNS: readonly SecretPattern[] = [
+	{ label: "AWS Access Key", regex: /AKIA[A-Z0-9]{16}/ },
+	{
+		label: "AWS Secret Key",
+		regex: /(?:aws_secret_access_key|secret_key)\s*[=:]\s*\S{20,}/i,
+	},
+	{ label: "GitHub Token", regex: /gh[ps]_[a-zA-Z0-9]{36,}/ },
+	{ label: "GitHub OAuth Token", regex: /gho_[a-zA-Z0-9]{36,}/ },
+	{ label: "Anthropic Key", regex: /sk-ant-[a-zA-Z0-9_-]{20,}/ },
+	{ label: "OpenAI Key", regex: /sk-[a-zA-Z0-9]{40,}/ },
+	{
+		label: "PEM Private Key",
+		regex: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----/,
+	},
+	{
+		label: "Generic Secret",
+		regex: /(?:secret|password|token|api_key|apikey|api-key)\s*[=:]\s*['"][^'"]{8,}['"]/i,
+	},
+	{ label: "Slack Token", regex: /xox[bpsa]-[a-zA-Z0-9-]{10,}/ },
+	{
+		label: "Stripe Key",
+		regex: /[sr]k_(?:live|test)_[a-zA-Z0-9]{20,}/,
+	},
+	{
+		label: "Google OAuth Secret",
+		regex: /GOCSPX-[a-zA-Z0-9_-]{28,}/,
+	},
+];
+
+// ---------------------------------------------------------------------------
+// Shannon entropy helper
+// ---------------------------------------------------------------------------
+
+/** Compute Shannon entropy (bits per character) of a string. */
+function shannonEntropy(s: string): number {
+	const freq = new Map<string, number>();
+	for (const ch of s) {
+		freq.set(ch, (freq.get(ch) ?? 0) + 1);
+	}
+	let entropy = 0;
+	for (const count of freq.values()) {
+		const p = count / s.length;
+		entropy -= p * Math.log2(p);
+	}
+	return entropy;
+}
+
+const ENTROPY_THRESHOLD = 4.0;
+const ENTROPY_MIN_LENGTH = 16;
+
+/**
+ * Match high-entropy values in `.env`-style assignments:
+ *   KEY=value  or  KEY="value"  or  KEY='value'
+ */
+const ENV_ASSIGNMENT = /^([A-Z_][A-Z0-9_]*)\s*=\s*['"]?([^'"#\s]+)['"]?/gm;
+
+// ---------------------------------------------------------------------------
+// Masking
+// ---------------------------------------------------------------------------
+
+/** Mask a secret value, keeping the first 4 and last 4 characters. */
+function mask(value: string): string {
+	if (value.length <= 10) return `${value.slice(0, 3)}****`;
+	return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Maximum bytes to scan (1 MB). */
+export const MAX_SCAN_BYTES = 1_048_576;
+
+/**
+ * Scan text content for known secret patterns and high-entropy values.
+ * Returns all matches with line numbers and masked snippets.
+ */
+export function scanForSecrets(content: string): ScanResult {
+	const matches: ScanMatch[] = [];
+	const lines = content.split("\n");
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const lineNum = i + 1;
+
+		// Check each known pattern
+		for (const { label, regex } of SECRET_PATTERNS) {
+			const match = regex.exec(line);
+			if (match) {
+				matches.push({
+					label,
+					line: lineNum,
+					snippet: mask(match[0]),
+				});
+			}
+		}
+
+		// Check high-entropy env-style assignments
+		let envMatch: RegExpExecArray | null;
+		ENV_ASSIGNMENT.lastIndex = 0;
+		while ((envMatch = ENV_ASSIGNMENT.exec(line)) !== null) {
+			const value = envMatch[2];
+			if (
+				value.length >= ENTROPY_MIN_LENGTH &&
+				shannonEntropy(value) >= ENTROPY_THRESHOLD
+			) {
+				// Avoid duplicate if already matched by a known pattern
+				const alreadyMatched = matches.some(
+					(m) => m.line === lineNum,
+				);
+				if (!alreadyMatched) {
+					matches.push({
+						label: "High-Entropy Value",
+						line: lineNum,
+						snippet: `${envMatch[1]}=${mask(value)}`,
+					});
+				}
+			}
+		}
+	}
+
+	return { hasSecrets: matches.length > 0, matches };
+}
+
+/**
+ * Returns true if the buffer likely contains binary data.
+ * Checks the first 512 bytes for null bytes.
+ */
+export function isBinaryContent(content: string): boolean {
+	const sample = content.slice(0, 512);
+	return sample.includes("\0");
+}

package/session.ts

@@ -0,0 +1,59 @@
+import type { ScanResult, WriteEntry } from "./types.js";
+
+/**
+ * Session-scoped state for Sentinel guards.
+ *
+ * Tracks files written during the session (Gap 3) and caches scan results
+ * to avoid redundant filesystem reads (Gap 2).
+ * Reset on every `session_start`.
+ */
+export class SentinelSession {
+	/** Files written during this session, keyed by absolute path. */
+	private writeRegistry = new Map<string, WriteEntry>();
+
+	/** Scan-result cache keyed by absolute path. Invalidated when mtime changes. */
+	private scanCache = new Map<string, { mtimeMs: number; result: ScanResult }>();
+
+	/** Clear all session state (called on session_start). */
+	reset(): void {
+		this.writeRegistry.clear();
+		this.scanCache.clear();
+	}
+
+	// -- Write registry (Gap 3) ------------------------------------------------
+
+	registerWrite(entry: WriteEntry): void {
+		this.writeRegistry.set(entry.path, entry);
+	}
+
+	getWrite(absolutePath: string): WriteEntry | undefined {
+		return this.writeRegistry.get(absolutePath);
+	}
+
+	// -- Scan cache (Gap 2) ----------------------------------------------------
+
+	getCachedScan(
+		absolutePath: string,
+		currentMtimeMs: number,
+	): ScanResult | undefined {
+		const cached = this.scanCache.get(absolutePath);
+		if (!cached) return undefined;
+		if (cached.mtimeMs !== currentMtimeMs) {
+			this.scanCache.delete(absolutePath);
+			return undefined;
+		}
+		return cached.result;
+	}
+
+	cacheScan(
+		absolutePath: string,
+		mtimeMs: number,
+		result: ScanResult,
+	): void {
+		this.scanCache.set(absolutePath, { mtimeMs, result });
+	}
+
+	invalidateScanCache(absolutePath: string): void {
+		this.scanCache.delete(absolutePath);
+	}
+}

package/types.ts

@@ -0,0 +1,39 @@
+/** Tri-state guard decision. */
+export type Decision =
+	| { action: "allow" }
+	| { action: "deny"; reason: string }
+	| { action: "ask"; title: string; message: string };
+
+/** A single secret match found during content scanning. */
+export type ScanMatch = {
+	/** Human-readable label, e.g. "AWS Access Key". */
+	label: string;
+	/** 1-based line number where the match was found. */
+	line: number;
+	/** Masked excerpt of the matched value. */
+	snippet: string;
+};
+
+/** Aggregated result of scanning content for secrets. */
+export type ScanResult = {
+	hasSecrets: boolean;
+	matches: ScanMatch[];
+};
+
+/** A dangerous-content pattern detected in written file content (Gap 3). */
+export type DangerousPattern = {
+	label: string;
+	pattern: RegExp;
+};
+
+/** Entry in the session write registry (Gap 3). */
+export type WriteEntry = {
+	/** Absolute path of the written file. */
+	path: string;
+	/** Timestamp (Date.now()) of the write. */
+	timestamp: number;
+	/** Whether dangerous execution patterns were detected in the content. */
+	hasDangerousContent: boolean;
+	/** Labels of detected dangerous patterns. */
+	dangerousPatterns: string[];
+};