@giuseppe.trisciuoglio/pi-prevent-destructive-commands 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- New per-project read-only mode (`/read-only on|off|status`): when enabled, every mutating tool call is blocked — `write`, `edit`, any patch-style tool (`*apply_patch`), `bash`, and `powershell` — while read-only tools (`read`, `grep`, `find`, `ls`) keep working. The flag lives in `.pi/prevent-destructive-commands.json` under `readOnly` (default `false` when the file is missing or invalid), `/read-only` toggles it while preserving unrelated JSON keys, and it is independent of the destructive-command, git, migration, Nx, and comment guards. Adds `test/read-only-command-test.ts` (`npm run test:read-only-command`) and `docs/adr/0001-read-only-mode.md`.
 - New guard: new comments in source files are blocked. Any tool call that would introduce a new comment into a source file (Java, TypeScript/JavaScript, Dart, Go, Rust, C/C++, C#, Swift, Kotlin, Scala, PHP, CSS/SCSS, Python, Ruby, shell, YAML, TOML, Terraform, GraphQL, SQL, Lua, Haskell, Elm, HTML/XML/SVG/Markdown) is stopped, covering `write`, `edit`, `apply_patch` (unified diff and `*** Begin Patch` formats), and bash write vectors (`cat > a.ts <<EOF`, `tee b.py <<EOF`, `echo "// x" >> c.ts`). Detection is string-aware (comment markers inside string literals are not comments), comments a file already contains may be carried over untouched, and shebang lines, tooling directives (`@ts-ignore`, `eslint-disable`, `biome-ignore`, `noqa`, …) and purely decorative lines are exempt. Opt out per project with `{"disableCommentGuard": true}` in the opt-out file. Adds `test/comment-guard-test.ts` (`npm run test:comment-guard`).
 - New guard: interactive `git commit` without a message option (bare `git commit`, `git commit -a`, `git commit --amend`, ...) is blocked because it opens the editor and hangs the session when the agent runs unattended. Applies unconditionally, even on projects that opted out of the git add/commit/push guards; commits with a message (`git commit -m x`, `-F file`, `--amend --no-edit`, ...) are unaffected.
 

package/README.md

@@ -19,6 +19,7 @@ A faithful port of Claude's [`prevent-destructive-commands.py`](https://github.c
 - **Recursive analysis** — Traverses command wrappers, shell invocations, pipelines, and nested commands to catch obfuscated attacks.
 - **Nx configuration guard** — In Nx workspaces, existing `package.json` and TypeScript configuration files are immutable to the agent; missing ones can still be created.
 - **Source comment guard** — The agent cannot introduce new comments into source files (Java, TypeScript, Dart, Python, SQL, HTML, and more) through writing tools or bash write vectors; existing comments may be carried over untouched and tooling directives (`@ts-ignore`, `eslint-disable`, …) stay allowed.
+- **Read-only mode** — `/read-only on` turns the project into an inspection-only workspace: `write`, `edit`, patch tools, `bash`, and `powershell` are blocked while `read`, `grep`, `find`, and `ls` keep working.
 - **Configurable** — Tune protection levels via simple flags in `src/config.ts`.
 - **Zero dependencies** — Lightweight, fast, and self-contained.
 - **79+ test cases** — Comprehensive smoke test suite validates all blocking rules.
@@ -112,7 +113,8 @@ Create `.pi/prevent-destructive-commands.json` in the project root to tune the g
 ```json
 {
 	"disableGitGuards": true,
-	"disableCommentGuard": true
+	"disableCommentGuard": true,
+	"readOnly": false
 }
 ```
 
@@ -120,6 +122,7 @@ Create `.pi/prevent-destructive-commands.json` in the project root to tune the g
 |------|---------|--------|
 | `disableGitGuards` | `false` | Disables the `git add` / `git commit` / `git push` guards. |
 | `disableCommentGuard` | `false` | Disables the source comment guard, allowing the agent to write comments into source files again. |
+| `readOnly` | `false` | When `true`, blocks every mutating tool call (`write`, `edit`, patch tools, `bash`, `powershell`) while read-only tools keep working. |
 
 Or use the `/git-guards` slash command from the pi TUI:
 
@@ -129,6 +132,18 @@ Or use the `/git-guards` slash command from the pi TUI:
 | `/git-guards off` | Write `{"disableGitGuards": true}` (unrelated JSON keys are preserved). |
 | `/git-guards on` | Write `{"disableGitGuards": false}`. |
 
+### Read-Only Mode
+
+Use the `/read-only` slash command to make the project inspection-only:
+
+| Command | Effect |
+|---------|--------|
+| `/read-only` | Show whether read-only mode is active for the current project, and the state of the configuration file. |
+| `/read-only on` | Write `{"readOnly": true}` (unrelated JSON keys are preserved). |
+| `/read-only off` | Write `{"readOnly": false}`. |
+
+While read-only mode is active, the agent can inspect files with `read`, `grep`, `find`, and `ls`, but `write`, `edit`, every patch-style tool, `bash`, and `powershell` are blocked with a clear reason. Read-only mode is independent of the destructive-command, git, migration, Nx, and comment guards, and it defaults to off when the configuration file is missing or invalid.
+
 Notes:
 
 - Forceful and deleting push variants (`--force`, `-f`, `--force-with-lease`, `-d`, `--delete`) are **always blocked** and cannot be opted out.
@@ -147,6 +162,7 @@ prevent-destructive-commands/
 │   ├── config.ts         # Blacklists and behavior flags — tune protection here
 │   ├── tokenizer.ts      # Shell tokenizer (shlex-like)
 │   ├── checker.ts        # Recursive command walker (wrappers/shell/find/xargs)
+│   ├── read-only-command.ts # /read-only toggle and read-only tool-call gate
 │   ├── migration-guard.ts
 │   ├── nx-guard.ts       # Protects existing Nx package and TypeScript configuration files
 │   ├── comment-guard.ts  # Blocks new comments written into source files

package/docs/adr/0001-read-only-mode.md

@@ -0,0 +1,53 @@
+# ADR 0001: Read-only mode blocks shell execution wholesale
+
+- Status: accepted
+- Date: 2026-10-23
+- Author: Giuseppe Trisciuoglio
+
+## Context
+
+The extension guards against destructive commands and protected paths, but there
+is no way to declare a project inspection-only. Users wanted a per-project flag
+that lets the agent read files and explore the codebase while preventing any
+modification. The natural home for the flag is the existing per-project
+configuration file, `.pi/prevent-destructive-commands.json`, and the `/git-guards`
+command already established the pattern of a user-invoked toggle that writes that
+file from the extension process.
+
+Tools that can mutate state are `write`, `edit`, any patch-style variant such as
+`apply_patch`, `bash`, and `powershell`. Read-only tools are `read`, `grep`,
+`find`, `ls`, and similar non-mutating tools.
+
+The open design question was whether read-only mode should keep allowing
+"obviously read-only" shell commands such as `cat`, `ls`, or `grep` invoked
+through `bash`. Classifying a shell command line as read-only is the same
+unsolved problem the destructive-command checker already deals with: commands
+can hide mutations behind wrappers, redirects, command substitution, heredocs,
+and arbitrary binaries.
+
+## Decision
+
+Read-only mode blocks `bash` and `powershell` entirely, without attempting to
+classify individual shell commands as safe. It also blocks `write`, `edit`, and
+every tool whose name ends with `apply_patch`. Read-only tools keep working.
+
+The mode is stored as a `readOnly` boolean in
+`.pi/prevent-destructive-commands.json`. It defaults to `false` when the file is
+missing or invalid, so the agent stays writable until the user explicitly turns
+it on. The `/read-only on|off|status` slash command toggles the flag while
+preserving unrelated JSON keys, mirroring `/git-guards`.
+
+When read-only mode is active, the `tool_call` handler checks it first and
+short-circuits the other write-related guards: a rejected write needs no further
+analysis.
+
+## Consequences
+
+- Inspection-only projects are safe: no shell invocation can mutate the
+  workspace while the mode is on.
+- Users lose the convenience of running read-only shell commands through `bash`
+  in read-only mode; they use `read`, `grep`, `find`, and `ls` instead.
+- The mode is per project, so different projects can be in different modes at
+  the same time.
+- Read-only mode is independent of the destructive-command, git, migration, Nx,
+  and comment guards; those behaviors are unchanged when the mode is off.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giuseppe.trisciuoglio/pi-prevent-destructive-commands",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Unconditionally blocks destructive bash commands before execution. A pi extension that guards against rm, git reset --hard, docker rm, aws delete operations, and more.",
   "keywords": [
     "pi-package",
@@ -32,7 +32,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "npm run test:smoke && npm run test:heredoc && npm run test:migration-guard && npm run test:nx-guard && npm run test:project-config && npm run test:find-start-path && npm run test:git-guards-command && npm run test:gh-guard && npm run test:comment-guard && npm run test:e2e",
+    "test": "npm run test:smoke && npm run test:heredoc && npm run test:migration-guard && npm run test:nx-guard && npm run test:project-config && npm run test:find-start-path && npm run test:git-guards-command && npm run test:read-only-command && npm run test:gh-guard && npm run test:comment-guard && npm run test:e2e",
     "test:smoke": "npx tsx test/smoke-test.ts",
     "test:heredoc": "npx tsx test/heredoc-test.ts",
     "test:e2e": "npx tsx test/e2e-install-test.ts",
@@ -41,6 +41,7 @@
     "test:project-config": "npx tsx test/project-config-test.ts",
     "test:find-start-path": "npx tsx test/find-start-path-test.ts",
     "test:git-guards-command": "npx tsx test/git-guards-command-test.ts",
+    "test:read-only-command": "npx tsx test/read-only-command-test.ts",
     "test:gh-guard": "npx tsx test/gh-guard-test.ts",
     "test:comment-guard": "npx tsx test/comment-guard-test.ts",
     "lint": "tsc --noEmit",

package/src/git-guards-command.ts

@@ -9,14 +9,12 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
 import { ENABLE_GIT_ADD_COMMIT_BLOCK } from "./config";
 import {
 	loadProjectConfig,
-	projectConfigPath,
 	PROJECT_CONFIG_RELATIVE_PATH,
-	resetProjectConfigCache,
+	projectConfigFileStatus,
+	writeProjectConfigFlag,
 } from "./project-config";
 
 export type GitGuardsAction = "status" | "off" | "on" | "usage";
@@ -48,26 +46,7 @@ export interface GitGuardsStatus {
 }
 
 export function gitGuardsStatus(cwd: string): GitGuardsStatus {
-	const path = projectConfigPath(cwd);
-
-	let fileExists = false;
-	try {
-		statSync(path);
-		fileExists = true;
-	} catch {
-		// No file: guards active by default.
-	}
-
-	let fileValid = !fileExists; // A missing file is not an invalid file.
-	if (fileExists) {
-		try {
-			const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
-			fileValid = typeof raw === "object" && raw !== null && !Array.isArray(raw);
-		} catch {
-			fileValid = false;
-		}
-	}
-
+	const { fileExists, fileValid } = projectConfigFileStatus(cwd);
 	const disabledByFile = loadProjectConfig(cwd).disableGitGuards;
 
 	return {
@@ -84,34 +63,9 @@ export function gitGuardsStatus(cwd: string): GitGuardsStatus {
  * file content was invalid (and therefore replaced).
  */
 export function applyGitGuards(cwd: string, disable: boolean): boolean {
-	const path = projectConfigPath(cwd);
-
-	let previous: Record<string, unknown> = {};
-	let replacedInvalid = false;
-	try {
-		const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
-		if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
-			previous = raw as Record<string, unknown>;
-		} else {
-			replacedInvalid = true;
-		}
-	} catch {
-		// Missing file or unparseable content: start from a clean object.
-		try {
-			statSync(path);
-			replacedInvalid = true;
-		} catch {
-			// File simply absent: nothing lost.
-		}
-	}
-
-	previous.disableGitGuards = disable;
-
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, `${JSON.stringify(previous, null, "\t")}\n`, "utf8");
-	resetProjectConfigCache();
-
-	return replacedInvalid;
+	return writeProjectConfigFlag(cwd, (config) => {
+		config.disableGitGuards = disable;
+	});
 }
 
 function statusMessage(cwd: string): { text: string; level: "info" | "warning" | "error" } {

package/src/index.ts

@@ -21,6 +21,7 @@ import {
 } from "./project-config";
 import { tokenize } from "./tokenizer";
 import { registerGitGuardsCommand } from "./git-guards-command";
+import { readOnlyBlockResult, registerReadOnlyCommand } from "./read-only-command";
 
 function pathsFromPatch(patch: string): string[] {
 	return extractPatchPaths(patch, [
@@ -52,8 +53,18 @@ function commandReferencesMigrationPath(command: string, cwd: string, migrationD
 
 export default function (pi: ExtensionAPI) {
 	registerGitGuardsCommand(pi);
+	registerReadOnlyCommand(pi);
 
 	pi.on("tool_call", async (event, ctx) => {
+		const projectConfig = ctx.cwd
+			? loadProjectConfig(ctx.cwd)
+			: DEFAULT_PROJECT_CONFIG;
+
+		const readOnlyBlock = readOnlyBlockResult(event.toolName, projectConfig);
+		if (readOnlyBlock) {
+			return readOnlyBlock;
+		}
+
 		// The per-project opt-out file is user-only: the agent must never create
 		// or edit it, neither through the writing tools nor through bash.
 		if (isToolCallEventType("bash", event)) {
@@ -84,10 +95,6 @@ export default function (pi: ExtensionAPI) {
 			return { block: true, reason: NX_CONFIG_BLOCK_REASON };
 		}
 
-		const projectConfig = ctx.cwd
-			? loadProjectConfig(ctx.cwd)
-			: DEFAULT_PROJECT_CONFIG;
-
 		if (!projectConfig.disableCommentGuard) {
 			const commentViolation = await findNewSourceComments(
 				event.toolName,

package/src/project-config.ts

@@ -8,8 +8,8 @@
  * user — the extension itself blocks the agent from writing to it.
  */
 
-import { readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 export const PROJECT_CONFIG_RELATIVE_PATH = ".pi/prevent-destructive-commands.json";
 
@@ -18,11 +18,13 @@ export interface ProjectConfig {
 	disableGitGuards: boolean;
 	/** When true, the source comment guard is disabled. */
 	disableCommentGuard: boolean;
+	readOnly: boolean;
 }
 
 export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
 	disableGitGuards: false,
 	disableCommentGuard: false,
+	readOnly: false,
 };
 
 /** Absolute path of the project configuration file for a given cwd. */
@@ -60,9 +62,11 @@ export function loadProjectConfig(cwd: string): ProjectConfig {
 	try {
 		const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
 		if (typeof raw === "object" && raw !== null) {
+			const fields = raw as Record<string, unknown>;
 			config = {
-				disableGitGuards: (raw as Record<string, unknown>).disableGitGuards === true,
-				disableCommentGuard: (raw as Record<string, unknown>).disableCommentGuard === true,
+				disableGitGuards: fields.disableGitGuards === true,
+				disableCommentGuard: fields.disableCommentGuard === true,
+				readOnly: fields.readOnly === true,
 			};
 		}
 	} catch {
@@ -92,3 +96,63 @@ export function commandReferencesProjectConfig(command: string): boolean {
 export function resetProjectConfigCache(): void {
 	cache.clear();
 }
+
+export interface ProjectConfigFileStatus {
+	fileExists: boolean;
+	fileValid: boolean;
+}
+
+export function projectConfigFileStatus(cwd: string): ProjectConfigFileStatus {
+	const path = projectConfigPath(cwd);
+
+	let fileExists = false;
+	try {
+		statSync(path);
+		fileExists = true;
+	} catch {
+	}
+
+	let fileValid = !fileExists;
+	if (fileExists) {
+		try {
+			const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
+			fileValid = typeof raw === "object" && raw !== null && !Array.isArray(raw);
+		} catch {
+			fileValid = false;
+		}
+	}
+
+	return { fileExists, fileValid };
+}
+
+export function writeProjectConfigFlag(
+	cwd: string,
+	mutate: (config: Record<string, unknown>) => void,
+): boolean {
+	const path = projectConfigPath(cwd);
+
+	let previous: Record<string, unknown> = {};
+	let replacedInvalid = false;
+	try {
+		const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+			previous = raw as Record<string, unknown>;
+		} else {
+			replacedInvalid = true;
+		}
+	} catch {
+		try {
+			statSync(path);
+			replacedInvalid = true;
+		} catch {
+		}
+	}
+
+	mutate(previous);
+
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(previous, null, "\t")}\n`, "utf8");
+	resetProjectConfigCache();
+
+	return replacedInvalid;
+}

package/src/read-only-command.ts

@@ -0,0 +1,131 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	loadProjectConfig,
+	PROJECT_CONFIG_RELATIVE_PATH,
+	projectConfigFileStatus,
+	writeProjectConfigFlag,
+} from "./project-config";
+
+export type ReadOnlyAction = "status" | "off" | "on" | "usage";
+
+export function parseReadOnlyArgs(args: string): ReadOnlyAction {
+	switch (args.trim().toLowerCase()) {
+		case "":
+		case "status":
+			return "status";
+		case "off":
+			return "off";
+		case "on":
+			return "on";
+		default:
+			return "usage";
+	}
+}
+
+export interface ReadOnlyStatus {
+	readOnly: boolean;
+	fileExists: boolean;
+	fileValid: boolean;
+}
+
+export function readOnlyStatus(cwd: string): ReadOnlyStatus {
+	const { fileExists, fileValid } = projectConfigFileStatus(cwd);
+	return {
+		readOnly: loadProjectConfig(cwd).readOnly,
+		fileExists,
+		fileValid,
+	};
+}
+
+export function applyReadOnly(cwd: string, value: boolean): boolean {
+	return writeProjectConfigFlag(cwd, (config) => {
+		config.readOnly = value;
+	});
+}
+
+function statusMessage(cwd: string): { text: string; level: "info" | "warning" | "error" } {
+	const status = readOnlyStatus(cwd);
+
+	const lines: string[] = [];
+	if (status.readOnly) {
+		lines.push("read-only mode is ACTIVE for this project: write, edit, patch, bash, and powershell are blocked.");
+	} else {
+		lines.push("read-only mode is INACTIVE for this project: mutating tools are allowed.");
+	}
+
+	if (!status.fileExists) {
+		lines.push(`configuration file: none (${PROJECT_CONFIG_RELATIVE_PATH} missing — safe default: read-only off)`);
+	} else if (!status.fileValid) {
+		lines.push(`configuration file: ${PROJECT_CONFIG_RELATIVE_PATH} exists but is not valid JSON — ignored, read-only off`);
+	} else {
+		lines.push(`configuration file: ${PROJECT_CONFIG_RELATIVE_PATH}`);
+	}
+
+	const level = status.readOnly ? "warning" : "info";
+	return { text: lines.join("\n"), level };
+}
+
+export const READ_ONLY_USAGE = `Usage: /read-only [on|off|status]
+  (no args)  show whether read-only mode is active for this project
+  on         write {"readOnly": true} to ${PROJECT_CONFIG_RELATIVE_PATH}
+  off        write {"readOnly": false} to ${PROJECT_CONFIG_RELATIVE_PATH}`;
+
+export const READ_ONLY_BLOCK_REASON =
+	"[prevent-destructive-commands] Blocked: read-only mode is enabled for this project (use /read-only off to allow modifications).";
+
+export function isReadOnlyMutatingTool(toolName: string): boolean {
+	return (
+		toolName === "write" ||
+		toolName === "edit" ||
+		toolName === "bash" ||
+		toolName === "powershell" ||
+		toolName.endsWith("apply_patch")
+	);
+}
+
+export interface ReadOnlyBlockResult {
+	block: true;
+	reason: string;
+}
+
+export function readOnlyBlockResult(
+	toolName: string,
+	config: { readOnly: boolean },
+): ReadOnlyBlockResult | undefined {
+	if (!config.readOnly || !isReadOnlyMutatingTool(toolName)) return undefined;
+	return { block: true, reason: READ_ONLY_BLOCK_REASON };
+}
+
+export function registerReadOnlyCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("read-only", {
+		description: "Show or toggle per-project read-only mode (/read-only [on|off])",
+		handler: async (args: string, ctx: { cwd: string; ui: { notify: (message: string, type?: "info" | "warning" | "error") => void } }) => {
+			switch (parseReadOnlyArgs(args)) {
+				case "status": {
+					const { text, level } = statusMessage(ctx.cwd);
+					ctx.ui.notify(text, level);
+					return;
+				}
+				case "on": {
+					const replacedInvalid = applyReadOnly(ctx.cwd, true);
+					ctx.ui.notify(
+						`read-only mode ENABLED for this project (write, edit, patch, bash, and powershell are blocked).${replacedInvalid ? ` Note: previous ${PROJECT_CONFIG_RELATIVE_PATH} was invalid JSON and was replaced.` : ""}`,
+						"warning",
+					);
+					return;
+				}
+				case "off": {
+					const replacedInvalid = applyReadOnly(ctx.cwd, false);
+					ctx.ui.notify(
+						`read-only mode DISABLED for this project (mutating tools allowed again).${replacedInvalid ? ` Note: previous ${PROJECT_CONFIG_RELATIVE_PATH} was invalid JSON and was replaced.` : ""}`,
+						"info",
+					);
+					return;
+				}
+				case "usage":
+					ctx.ui.notify(READ_ONLY_USAGE, "error");
+					return;
+			}
+		},
+	});
+}

package/test/git-guards-command-test.ts

@@ -13,7 +13,15 @@ import {
 	parseGitGuardsArgs,
 } from "../src/git-guards-command";
 import { PROJECT_CONFIG_RELATIVE_PATH, loadProjectConfig } from "../src/project-config";
-import { check, checkFailures, isBlocked, makeProject } from "./helpers";
+import {
+	check,
+	checkFileStatusOnInvalidConfig,
+	checkUnknownArgument,
+	finishTest,
+	isBlocked,
+	makeProject,
+	setupCommandHarness,
+} from "./helpers";
 
 // ─── parseGitGuardsArgs ───────────────────────────────────────────────────────
 
@@ -48,14 +56,9 @@ const disabledFile = makeProject('{"disableGitGuards": true}');
 }
 rmSync(disabledFile, { recursive: true, force: true });
 
-const invalidFile = makeProject("{ not json");
-{
-	const status = gitGuardsStatus(invalidFile);
+checkFileStatusOnInvalidConfig("git-guards", gitGuardsStatus, (status) => {
 	check("invalid JSON → guards stay enabled", status.guardsEnabled, true);
-	check("invalid JSON → fileExists true", status.fileExists, true);
-	check("invalid JSON → fileValid false", status.fileValid, false);
-}
-rmSync(invalidFile, { recursive: true, force: true });
+});
 
 // ─── applyGitGuards ──────────────────────────────────────────────────────────
 
@@ -111,42 +114,14 @@ const broken = makeProject("{ not json");
 }
 rmSync(broken, { recursive: true, force: true });
 
-// ─── registerGitGuardsCommand (handler wiring with a fake pi/ctx) ───────────
-
-interface RecordedNotification {
-	message: string;
-	type: string;
-}
-
-function fakePi() {
-	const commands = new Map<string, { description?: string; handler: (args: string, ctx: unknown) => Promise<void> }>();
-	return {
-		commands,
-		registerCommand: (name: string, options: { description?: string; handler: (args: string, ctx: unknown) => Promise<void> }) => {
-			commands.set(name, options);
-		},
-	};
-}
-
-function fakeCtx(cwd: string) {
-	const notifications: RecordedNotification[] = [];
-	return {
-		notifications,
-		ctx: { cwd, ui: { notify: (message: string, type = "info") => notifications.push({ message, type }) } },
-	};
-}
-
 const commandProject = makeProject();
 {
-	const pi = fakePi();
-	registerGitGuardsCommand(pi as unknown as Parameters<typeof registerGitGuardsCommand>[0]);
-	check("command registered as git-guards", pi.commands.has("git-guards"), true);
-	check("command has a description", typeof pi.commands.get("git-guards")?.description, "string");
-
-	const handler = pi.commands.get("git-guards")!.handler;
-	const { ctx, notifications } = fakeCtx(commandProject);
+	const { handler, ctx, notifications } = setupCommandHarness(
+		commandProject,
+		"git-guards",
+		(pi) => registerGitGuardsCommand(pi as unknown as Parameters<typeof registerGitGuardsCommand>[0]),
+	);
 
-	ctx.cwd = commandProject;
 	handler("", ctx);
 	check("status notifies once", notifications.length, 1);
 	check("status mentions ACTIVE", notifications[0].message.includes("ACTIVE"), true);
@@ -164,20 +139,10 @@ const commandProject = makeProject();
 	check("on notifies once", notifications.length, 4);
 	check("on effect via loadProjectConfig", loadProjectConfig(commandProject).disableGitGuards, false);
 
-	handler("bogus", ctx);
-	check("unknown arg notifies once", notifications.length, 5);
-	check("unknown arg shows usage", notifications[4].message.includes("Usage:"), true);
-	check("unknown arg notification is an error", notifications[4].type, "error");
+	checkUnknownArgument(handler, ctx, notifications);
 }
 rmSync(commandProject, { recursive: true, force: true });
 
-// ─── result ──────────────────────────────────────────────────────────────────
-
 rmSync(noFile, { recursive: true, force: true });
 
-if (checkFailures() > 0) {
-	console.error(`\n${checkFailures()} git-guards command test(s) failed.`);
-	process.exit(1);
-} else {
-	console.log("\nAll git-guards command tests passed.");
-}
+finishTest("git-guards command");

package/test/helpers.ts

@@ -110,4 +110,100 @@ export async function runIsolatedTest(name: string, body: (root: string) => Prom
 		console.error(error);
 		process.exit(1);
 	});
+}
+
+export interface RecordedNotification {
+	message: string;
+	type: string;
+}
+
+export type FakeCommandHandler = (args: string, ctx: unknown) => Promise<void> | void;
+
+export interface FakePi {
+	commands: Map<string, { description?: string; handler: FakeCommandHandler }>;
+	registerCommand: (name: string, options: { description?: string; handler: FakeCommandHandler }) => void;
+}
+
+export function fakePi(): FakePi {
+	const commands = new Map<string, { description?: string; handler: FakeCommandHandler }>();
+	return {
+		commands,
+		registerCommand: (name, options) => {
+			commands.set(name, options);
+		},
+	};
+}
+
+export function fakeCtx(cwd: string) {
+	const notifications: RecordedNotification[] = [];
+	return {
+		notifications,
+		ctx: { cwd, ui: { notify: (message: string, type = "info") => notifications.push({ message, type }) } },
+	};
+}
+
+export interface CommandHarness {
+	handler: FakeCommandHandler;
+	ctx: { cwd: string; ui: { notify: (message: string, type?: string) => void } };
+	notifications: RecordedNotification[];
+}
+
+export function setupCommandHarness(
+	project: string,
+	commandName: string,
+	register: (pi: FakePi) => void,
+): CommandHarness {
+	const pi = fakePi();
+	register(pi);
+	check(`command registered as ${commandName}`, pi.commands.has(commandName), true);
+	check("command has a description", typeof pi.commands.get(commandName)?.description, "string");
+
+	const handler = pi.commands.get(commandName)!.handler;
+	const { ctx, notifications } = fakeCtx(project);
+	ctx.cwd = project;
+
+	return { handler, ctx, notifications };
+}
+
+export function checkUnknownArgument(
+	handler: FakeCommandHandler,
+	ctx: unknown,
+	notifications: RecordedNotification[],
+): void {
+	const before = notifications.length;
+	handler("bogus", ctx);
+	check("unknown arg notifies once", notifications.length, before + 1);
+	const last = notifications[notifications.length - 1];
+	check("unknown arg shows usage", last.message.includes("Usage:"), true);
+	check("unknown arg notification is an error", last.type, "error");
+}
+
+export interface ConfigFileStatus {
+	fileExists: boolean;
+	fileValid: boolean;
+}
+
+export function checkFileStatusOnInvalidConfig<T extends ConfigFileStatus>(
+	label: string,
+	statusFn: (cwd: string) => T,
+	extra?: (status: T) => void,
+): void {
+	const project = makeProject("{ not json");
+	try {
+		const status = statusFn(project);
+		extra?.(status);
+		check(`${label}: invalid JSON → fileExists true`, status.fileExists, true);
+		check(`${label}: invalid JSON → fileValid false`, status.fileValid, false);
+	} finally {
+		rmSync(project, { recursive: true, force: true });
+	}
+}
+
+export function finishTest(label: string): void {
+	if (checkFailures() > 0) {
+		console.error(`\n${checkFailures()} ${label} test(s) failed.`);
+		process.exit(1);
+	} else {
+		console.log(`\nAll ${label} tests passed.`);
+	}
 }

package/test/read-only-command-test.ts

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	READ_ONLY_BLOCK_REASON,
+	applyReadOnly,
+	isReadOnlyMutatingTool,
+	parseReadOnlyArgs,
+	readOnlyBlockResult,
+	readOnlyStatus,
+	registerReadOnlyCommand,
+} from "../src/read-only-command";
+import { PROJECT_CONFIG_RELATIVE_PATH, loadProjectConfig } from "../src/project-config";
+import {
+	check,
+	checkFileStatusOnInvalidConfig,
+	checkUnknownArgument,
+	finishTest,
+	makeProject,
+	setupCommandHarness,
+} from "./helpers";
+
+check("no args → status", parseReadOnlyArgs(""), "status");
+check("'  ' → status", parseReadOnlyArgs("   "), "status");
+check("'status' → status", parseReadOnlyArgs("status"), "status");
+check("'STATUS' → status (case-insensitive)", parseReadOnlyArgs("STATUS"), "status");
+check("'on' → on", parseReadOnlyArgs("on"), "on");
+check("'off' → off", parseReadOnlyArgs("off"), "off");
+check("'foo' → usage", parseReadOnlyArgs("foo"), "usage");
+check("'true' → usage", parseReadOnlyArgs("true"), "usage");
+
+const noFile = makeProject();
+{
+	const status = readOnlyStatus(noFile);
+	check("missing file → readOnly false", status.readOnly, false);
+	check("missing file → fileExists false", status.fileExists, false);
+	check("missing file → fileValid true", status.fileValid, true);
+}
+
+const enabledFile = makeProject('{"readOnly": true}');
+{
+	const status = readOnlyStatus(enabledFile);
+	check("readOnly: true → readOnly true", status.readOnly, true);
+	check("readOnly: true → fileExists true", status.fileExists, true);
+	check("readOnly: true → fileValid true", status.fileValid, true);
+}
+rmSync(enabledFile, { recursive: true, force: true });
+
+checkFileStatusOnInvalidConfig("read-only", readOnlyStatus, (status) => {
+	check("invalid JSON → readOnly false", status.readOnly, false);
+});
+
+const empty = makeProject();
+{
+	const replacedInvalid = applyReadOnly(empty, true);
+	check("on on missing file → no replaced-invalid flag", replacedInvalid, false);
+	check("on creates the file", existsSync(join(empty, ...PROJECT_CONFIG_RELATIVE_PATH.split("/"))), true);
+	const raw: unknown = JSON.parse(readFileSync(join(empty, ...PROJECT_CONFIG_RELATIVE_PATH.split("/")), "utf8"));
+	check("on writes readOnly: true", (raw as Record<string, unknown>).readOnly, true);
+	check("on visible via loadProjectConfig", loadProjectConfig(empty).readOnly, true);
+
+	writeFileSync(
+		join(empty, ...PROJECT_CONFIG_RELATIVE_PATH.split("/")),
+		'{"disableGitGuards": true, "futureOption": 42}',
+	);
+	applyReadOnly(empty, false);
+	const merged: unknown = JSON.parse(readFileSync(join(empty, ...PROJECT_CONFIG_RELATIVE_PATH.split("/")), "utf8"));
+	check("off writes readOnly: false", (merged as Record<string, unknown>).readOnly, false);
+	check("off preserves disableGitGuards", (merged as Record<string, unknown>).disableGitGuards, true);
+	check("off preserves unrelated keys", (merged as Record<string, unknown>).futureOption, 42);
+	check("off visible via loadProjectConfig", loadProjectConfig(empty).readOnly, false);
+}
+rmSync(empty, { recursive: true, force: true });
+
+const broken = makeProject("{ not json");
+{
+	const replacedInvalid = applyReadOnly(broken, true);
+	check("on on invalid file → reports replacement", replacedInvalid, true);
+	const status = readOnlyStatus(broken);
+	check("invalid file normalized after on", status.fileValid, true);
+	check("normalized file → readOnly true", status.readOnly, true);
+}
+rmSync(broken, { recursive: true, force: true });
+
+check("write is mutating", isReadOnlyMutatingTool("write"), true);
+check("edit is mutating", isReadOnlyMutatingTool("edit"), true);
+check("apply_patch is mutating", isReadOnlyMutatingTool("apply_patch"), true);
+check("custom apply_patch variant is mutating", isReadOnlyMutatingTool("smart_apply_patch"), true);
+check("bash is mutating", isReadOnlyMutatingTool("bash"), true);
+check("powershell is mutating", isReadOnlyMutatingTool("powershell"), true);
+check("read is read-only", isReadOnlyMutatingTool("read"), false);
+check("grep is read-only", isReadOnlyMutatingTool("grep"), false);
+check("find is read-only", isReadOnlyMutatingTool("find"), false);
+check("ls is read-only", isReadOnlyMutatingTool("ls"), false);
+
+check("read-only off → write not blocked", readOnlyBlockResult("write", { readOnly: false }), undefined);
+check(
+	"read-only on → write blocked",
+	readOnlyBlockResult("write", { readOnly: true }),
+	{ block: true, reason: READ_ONLY_BLOCK_REASON },
+);
+check(
+	"read-only on → bash blocked",
+	readOnlyBlockResult("bash", { readOnly: true }),
+	{ block: true, reason: READ_ONLY_BLOCK_REASON },
+);
+check("read-only on → read allowed", readOnlyBlockResult("read", { readOnly: true }), undefined);
+check("block reason identifies the cause", READ_ONLY_BLOCK_REASON.includes("read-only mode is enabled"), true);
+
+const readOnlyProject = makeProject('{"readOnly": true, "disableGitGuards": true}');
+{
+	check("read-only project config loads readOnly", loadProjectConfig(readOnlyProject).readOnly, true);
+	check("read-only project still parses other keys", loadProjectConfig(readOnlyProject).disableGitGuards, true);
+	check(
+		"matrix: write blocked in read-only project",
+		readOnlyBlockResult("write", loadProjectConfig(readOnlyProject)),
+		{ block: true, reason: READ_ONLY_BLOCK_REASON },
+	);
+}
+rmSync(readOnlyProject, { recursive: true, force: true });
+
+const commandProject = makeProject();
+{
+	const { handler, ctx, notifications } = setupCommandHarness(
+		commandProject,
+		"read-only",
+		(pi) => registerReadOnlyCommand(pi as unknown as Parameters<typeof registerReadOnlyCommand>[0]),
+	);
+
+	handler("", ctx);
+	check("status notifies once", notifications.length, 1);
+	check("status mentions INACTIVE", notifications[0].message.includes("INACTIVE"), true);
+	check("status mentions missing file", notifications[0].message.includes("missing"), true);
+
+	handler("on", ctx);
+	check("on notifies once", notifications.length, 2);
+	check("on notification is a warning", notifications[1].type, "warning");
+	check("on effect via loadProjectConfig", loadProjectConfig(commandProject).readOnly, true);
+
+	handler("", ctx);
+	check("status after on mentions ACTIVE", notifications[2].message.includes("ACTIVE"), true);
+
+	handler("off", ctx);
+	check("off notifies once", notifications.length, 4);
+	check("off effect via loadProjectConfig", loadProjectConfig(commandProject).readOnly, false);
+
+	checkUnknownArgument(handler, ctx, notifications);
+}
+rmSync(commandProject, { recursive: true, force: true });
+
+rmSync(noFile, { recursive: true, force: true });
+
+finishTest("read-only command");