pi-simple-english 0.8.1 → 0.10.0

package/README.md

@@ -78,6 +78,16 @@ The `write-simple-english` skill carries the rules, so the agent
 writes clean prose the first time. The `lint-simple-english` skill
 tells the agent to lint the prose it writes and fix every finding.
 
+## Toggle
+
+Turn the linter off for the session with `/se off`. That hides the
+`se_lint` tool and stops the edit enforcement. Turn it back on with
+`/se on`, or run `/se` to flip the current state. The status line
+shows `● simple-english` while it is on.
+
+The toggle lasts for the session. To stop the linter for every
+session, uninstall the package: `pi uninstall npm:pi-simple-english`.
+
 ## Versions
 
 The package version tracks the gem version. The changelog lives in

package/extensions/se-lint.ts

@@ -1,13 +1,14 @@
 /**
  * se_lint - lint Markdown prose and code comments with simple_english.
  *
- * Two layers. The se_lint tool lints on demand. Enforcement runs the
+ * Three layers. The se_lint tool lints on demand. Enforcement runs the
  * same lint after every edit or write and appends the findings to the
  * tool result, so the agent sees them in the turn that made them. It
- * never blocks the edit. The contract mirrors the claude-code hook in
- * integrations/claude-code/hooks/lint.sh: a clean file stays silent,
- * a failed lint says so instead of reading as clean, and a missing
- * binary names the install step.
+ * never blocks the edit. The /se command gates both layers per session:
+ * off hides the tool from the model and skips enforcement. The contract
+ * mirrors the claude-code hook in integrations/claude-code/hooks/lint.sh:
+ * a clean file stays silent, a failed lint says so instead of reading as
+ * clean, and a missing binary names the install step.
  */
 
 import { execFile } from "node:child_process";
@@ -15,6 +16,7 @@ import { Type } from "typebox";
 import type {
 	AgentToolResult,
 	ExtensionAPI,
+	ExtensionContext,
 	ToolResultEvent,
 	ToolResultEventResult,
 } from "@earendil-works/pi-coding-agent";
@@ -24,6 +26,9 @@ const OUTPUT_LIMIT = 4000;
 // ever proves slow in practice, cut to 30s and pre-warm via `se serve`.
 const TIMEOUT_MS = 120_000;
 
+const STATE_ENTRY_TYPE = "se-lint-state";
+const STATUS_KEY = "se";
+
 interface SeResult {
 	stdout: string;
 	code: number;
@@ -36,6 +41,8 @@ interface SeDetails {
 	full?: string;
 }
 
+type SeLintState = { enabled: boolean };
+
 function seLint(path: string, signal?: AbortSignal): Promise<SeResult> {
 	return new Promise((resolve, reject) => {
 		execFile(
@@ -81,60 +88,131 @@ async function lintFeedback(path: string): Promise<string | undefined> {
 	return `se found ${findings} lint finding(s) in ${path}. Fix them, then lint again:\n${text}`;
 }
 
+// The last state entry on the branch wins. Earlier toggles are history,
+// not the current state.
+function savedEnabled(ctx: ExtensionContext): boolean | undefined {
+	let saved: boolean | undefined;
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.type !== "custom" || entry.customType !== STATE_ENTRY_TYPE) {
+			continue;
+		}
+		const data = entry.data as Partial<SeLintState> | undefined;
+		if (typeof data?.enabled === "boolean") {
+			saved = data.enabled;
+		}
+	}
+	return saved;
+}
+
 export default function (pi: ExtensionAPI) {
-	pi.registerTool({
-		name: "se_lint",
-		label: "Lint prose",
-		description:
-			"Lint Markdown prose and code comments against plain-English rules (short sentences, active voice, no jargon, no filler). " +
-			"Call this after writing or editing any documentation file (.md) or prose-heavy text to verify it reads clean. " +
-			"Also call it on demand when asked to lint or simplify text. " +
-			"Input: a file or directory path. Returns findings with line numbers and suggested rewrites, or 'clean' when nothing is flagged. " +
-			"After fixing findings, re-run until it reports clean.",
-		parameters: Type.Object({
-			path: Type.String({ description: "File or directory to lint, relative to the CWD or absolute" }),
-		}),
-
-		async execute(_toolCallId, params, signal): Promise<AgentToolResult<SeDetails>> {
-			let stdout: string;
-			let code: number;
-			try {
-				({ stdout, code } = await seLint(params.path, signal));
-			} catch (err) {
-				const e = err as NodeJS.ErrnoException;
-				if (e.code === "ENOENT") {
-					throw new Error(
-						"`se` not found. Install it first: `gem install simple_english`, then retry.",
-					);
+	let enabled = true;
+
+	const updateStatus = (ctx: ExtensionContext): void => {
+		if (!enabled) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
+		const dot = ctx.ui.theme.fg("success", "●");
+		ctx.ui.setStatus(STATUS_KEY, `${dot} ${ctx.ui.theme.fg("accent", "simple-english")}`);
+	};
+
+	const registerLintTool = (exposure: "direct" | "hidden"): void => {
+		pi.registerTool({
+			name: "se_lint",
+			label: "Lint prose",
+			description:
+				"Lint Markdown prose and code comments against plain-English rules (short sentences, active voice, no jargon, no filler). " +
+				"Call this after writing or editing any documentation file (.md) or prose-heavy text to verify it reads clean. " +
+				"Also call it on demand when asked to lint or simplify text. " +
+				"Input: a file or directory path. Returns findings with line numbers and suggested rewrites, or 'clean' when nothing is flagged. " +
+				"After fixing findings, re-run until it reports clean.",
+			parameters: Type.Object({
+				path: Type.String({ description: "File or directory path to lint, relative to the CWD or absolute" }),
+			}),
+			exposure,
+
+			async execute(_toolCallId, params, signal): Promise<AgentToolResult<SeDetails>> {
+				let stdout: string;
+				let code: number;
+				try {
+					({ stdout, code } = await seLint(params.path, signal));
+				} catch (err) {
+					const e = err as NodeJS.ErrnoException;
+					if (e.code === "ENOENT") {
+						throw new Error(
+							"`se` not found. Install it first: `gem install simple_english`, then retry.",
+						);
+					}
+					throw new Error(`se lint failed: ${e.message}`);
 				}
-				throw new Error(`se lint failed: ${e.message}`);
-			}
 
-			if (code !== 0 && code !== 1) {
-				throw new Error(`se lint exited with code ${code}: ${stdout.trim()}`);
-			}
+				if (code !== 0 && code !== 1) {
+					throw new Error(`se lint exited with code ${code}: ${stdout.trim()}`);
+				}
 
-			const full = stdout.trim();
-			if (!full) {
+				const full = stdout.trim();
+				if (!full) {
+					return {
+						content: [{ type: "text" as const, text: `clean: no findings in ${params.path}` }],
+						details: { path: params.path, exitCode: code, findings: 0, full: undefined },
+					};
+				}
+
+				const findings = full.split("\n").length;
+				const text =
+					full.length > OUTPUT_LIMIT
+						? `${full.slice(0, OUTPUT_LIMIT)}\n... truncated (${full.length} chars, ${findings} findings). Full output: run \`se lint ${params.path}\` with bash.`
+						: `${findings} finding(s) in ${params.path}:\n${full}`;
 				return {
-					content: [{ type: "text" as const, text: `clean: no findings in ${params.path}` }],
-					details: { path: params.path, exitCode: code, findings: 0, full: undefined },
+					content: [{ type: "text" as const, text }],
+					details: { path: params.path, exitCode: code, findings, full },
 				};
+			},
+		});
+	};
+
+	const setEnabled = (next: boolean, ctx: ExtensionContext): void => {
+		enabled = next;
+		pi.appendEntry(STATE_ENTRY_TYPE, { enabled } satisfies SeLintState);
+		registerLintTool(next ? "direct" : "hidden");
+		updateStatus(ctx);
+		ctx.ui.notify(`Prose lint ${next ? "on" : "off"}`, "info");
+	};
+
+	const restoreState = (ctx: ExtensionContext): void => {
+		enabled = savedEnabled(ctx) ?? true;
+		registerLintTool(enabled ? "direct" : "hidden");
+		updateStatus(ctx);
+	};
+
+	registerLintTool("direct");
+
+	pi.registerCommand("se", {
+		description: "Toggle prose linting (se_lint tool and edit enforcement) for this session",
+		handler: async (args, ctx) => {
+			const argument = args.trim().toLowerCase();
+
+			if (argument === "") {
+				setEnabled(!enabled, ctx);
+				return;
+			}
+
+			if (argument === "on") {
+				setEnabled(true, ctx);
+				return;
 			}
 
-			const findings = full.split("\n").length;
-			const text =
-				full.length > OUTPUT_LIMIT
-					? `${full.slice(0, OUTPUT_LIMIT)}\n... truncated (${full.length} chars, ${findings} findings). Full output: run \`se lint ${params.path}\` with bash.`
-					: `${findings} finding(s) in ${params.path}:\n${full}`;
-			return {
-				content: [{ type: "text" as const, text }],
-				details: { path: params.path, exitCode: code, findings, full },
-			};
+			if (argument === "off" || argument === "stop") {
+				setEnabled(false, ctx);
+				return;
+			}
+
+			ctx.ui.notify("Usage: /se [on|off]", "warning");
 		},
 	});
 
 	pi.on("tool_result", async (event: ToolResultEvent): Promise<ToolResultEventResult | undefined> => {
+		if (!enabled) return;
 		if (event.toolName !== "edit" && event.toolName !== "write") return;
 		// A failed edit wrote nothing: there is nothing to lint.
 		if (event.isError) return;
@@ -144,4 +222,7 @@ export default function (pi: ExtensionAPI) {
 		if (!feedback) return;
 		return { content: [...event.content, { type: "text" as const, text: feedback }] };
 	});
+
+	pi.on("session_start", async (_event, ctx) => restoreState(ctx));
+	pi.on("session_tree", async (_event, ctx) => restoreState(ctx));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simple-english",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Lint prose and code comments with the simple_english plain-English rules.",
   "type": "module",
   "license": "MIT",

package/skills/lint-simple-english/SKILL.md

@@ -7,7 +7,8 @@ description: Lint prose with simple_english after writing or editing documentati
 
 Lint prose the linter can see. Call the lint tool after writing or
 editing any documentation file or prose-heavy text. Read the findings.
-Fix every finding. Re-run until the result is clean.
+Fix every finding, also in prose you did not write. Re-run
+until the result is clean.
 
 The tool names differ by agent: