@xynogen/pix-optimizer 1.0.0 → 1.0.2

package/README.md

@@ -78,7 +78,7 @@ npm i -g @toon-format/cli
 ## Installation
 
 ```bash
-pi install git:github.com/xynogen/pix-optimizer
+pi install npm:@xynogen/pix-optimizer
 ```
 
 ## Architecture
@@ -101,6 +101,30 @@ that `/opt` dispatches to. All three share one `OptimizerStatus`.
 bun test
 ```
 
+## Origin
+
+This package was built by merging two upstream Pi community packages:
+
+- **Caveman mode** — merged from [`git:github.com/jonjonrankin/pi-caveman`](https://github.com/jonjonrankin/pi-caveman)
+  (itself a fork of `npm:pi-caveman`). Reimplemented here with multiple compression levels,
+  a settings dialog, per-session persistence, and integration with the shared `/opt` command.
+
+- **RTK rewriting** — merged from `npm:pi-rtk-optimizer`. Reimplemented here with a two-layer
+  approach: prompt injection + live bash command rewriting that handles chained commands
+  (`&&`, `||`, `;`, `|`).
+
+Both upstreams are MIT licensed. Neither codebase was copied directly — the logic was
+rewritten and combined into a single extension with a unified `/opt` command and shared status bar.
+This package does not sync back to either upstream.
+
+## Full distro
+
+To install the complete pix suite (all packages + Pi itself):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,48 +1,53 @@
 {
-  "name": "@xynogen/pix-optimizer",
-  "version": "1.0.0",
-  "description": "Performance optimization suite for Pi Coding Agent - caveman mode + RTK tool rewriting + jq/TOON JSON compression",
-  "type": "module",
-  "main": "src/index.ts",
-  "scripts": {
-    "test": "bun test"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "extensions": ["./src/index.ts"]
-  },
-  "keywords": [
-    "pi",
-    "pi-package",
-    "pi-extension",
-    "optimizer",
-    "caveman",
-    "rtk",
-    "toon",
-    "jq",
-    "json",
-    "performance"
-  ],
-  "author": "xynogen",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/xynogen/pix-mono.git",
-    "directory": "packages/pix-optimizer"
-  },
-  "homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-optimizer#readme",
-  "bugs": {
-    "url": "https://github.com/xynogen/pix-mono/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
-  }
+	"name": "@xynogen/pix-optimizer",
+	"version": "1.0.2",
+	"description": "Performance optimization suite for Pi Coding Agent - caveman mode + RTK tool rewriting + jq/TOON JSON compression",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		],
+		"skills": [
+			"./src/skills"
+		]
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"optimizer",
+		"caveman",
+		"rtk",
+		"toon",
+		"jq",
+		"json",
+		"performance"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-optimizer"
+	},
+	"homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-optimizer#readme",
+	"bugs": {
+		"url": "https://github.com/xynogen/pix-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
 }

package/src/caveman.test.ts

@@ -1,16 +1,16 @@
-import { describe, it, expect } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import {
-	LEVELS,
-	LEVEL_NUMBERS,
-	STOP_ALIASES,
-	STATUS_LABELS,
-	buildPrompt,
 	buildHelp,
-	resolveLevel,
-	toggleLevel,
-	parseConfig,
+	buildPrompt,
 	DEFAULT_CONFIG,
+	LEVEL_NUMBERS,
+	LEVELS,
 	type Level,
+	parseConfig,
+	resolveLevel,
+	STATUS_LABELS,
+	STOP_ALIASES,
+	toggleLevel,
 } from "./caveman.ts";
 
 // ── LEVELS ────────────────────────────────────────────────────────────────────
@@ -21,7 +21,7 @@ describe("LEVELS", () => {
 	});
 
 	it("contains all expected levels", () => {
-		const expected = ["off", "lite", "full", "ultra", "micro"];
+		const expected: Level[] = ["off", "lite", "full", "ultra", "micro"];
 		for (const l of expected) expect(LEVELS).toContain(l);
 	});
 });
@@ -52,10 +52,10 @@ describe("STATUS_LABELS", () => {
 	});
 
 	it("latin levels are uppercase", () => {
-		expect(STATUS_LABELS["lite"]).toBe("LITE");
-		expect(STATUS_LABELS["full"]).toBe("FULL");
-		expect(STATUS_LABELS["ultra"]).toBe("ULTRA");
-		expect(STATUS_LABELS["micro"]).toBe("MICRO");
+		expect(STATUS_LABELS.lite).toBe("LITE");
+		expect(STATUS_LABELS.full).toBe("FULL");
+		expect(STATUS_LABELS.ultra).toBe("ULTRA");
+		expect(STATUS_LABELS.micro).toBe("MICRO");
 	});
 });
 
@@ -202,7 +202,6 @@ describe("buildPrompt", () => {
 		expect(ultra).toContain("Abbreviate");
 		expect(lite).not.toContain("Abbreviate");
 	});
-
 });
 
 // ── parseConfig ───────────────────────────────────────────────────────────────
@@ -233,7 +232,9 @@ describe("parseConfig", () => {
 
 	it("accepts all valid levels as defaultLevel", () => {
 		for (const l of LEVELS) {
-			expect(parseConfig({ defaultLevel: l, showStatus: true }).defaultLevel).toBe(l);
+			expect(
+				parseConfig({ defaultLevel: l, showStatus: true }).defaultLevel,
+			).toBe(l);
 		}
 	});
 });

package/src/caveman.ts

@@ -5,7 +5,7 @@
  * called by index.ts alongside rtk(pi).
  */
 
-import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type {
@@ -14,23 +14,17 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
-import type { OptimizerHandle, OptimizerStatus } from "./status.ts";
 import {
 	Container,
 	type SettingItem,
 	SettingsList,
 	Text,
 } from "@earendil-works/pi-tui";
+import type { OptimizerHandle, OptimizerStatus } from "./status.ts";
 
 // ── Levels ────────────────────────────────────────────────────────────────────
 
-export const LEVELS = [
-	"off",
-	"lite",
-	"full",
-	"ultra",
-	"micro",
-] as const;
+export const LEVELS = ["off", "lite", "full", "ultra", "micro"] as const;
 
 export type Level = (typeof LEVELS)[number];
 
@@ -43,27 +37,31 @@ export const LEVEL_NUMBERS: Record<string, Level> = {
 	"3": "ultra",
 };
 
-export const CAVEMAN_COMMAND_OPTIONS = [
-	{ value: "1",             label: "1 (lite)",      description: "Professional, no fluff" },
-	{ value: "2",             label: "2 (full)",      description: "Classic caveman" },
-	{ value: "3",             label: "3 (ultra)",     description: "Maximum compression" },
-	{ value: "lite",          label: "lite",          description: "Professional, no fluff" },
-	{ value: "full",          label: "full",          description: "Classic caveman" },
-	{ value: "ultra",         label: "ultra",         description: "Maximum compression" },
-	{ value: "micro",         label: "micro",         description: "Experimental prompt-minimized mode" },
-	{ value: "off",           label: "off",           description: "Disable caveman mode" },
-	{ value: "stop",          label: "stop",          description: "Disable caveman mode" },
-	{ value: "quit",          label: "quit",          description: "Disable caveman mode" },
-	{ value: "config",        label: "config",        description: "Open settings dialog" },
+const CAVEMAN_COMMAND_OPTIONS = [
+	{ value: "1", label: "1 (lite)", description: "Professional, no fluff" },
+	{ value: "2", label: "2 (full)", description: "Classic caveman" },
+	{ value: "3", label: "3 (ultra)", description: "Maximum compression" },
+	{ value: "lite", label: "lite", description: "Professional, no fluff" },
+	{ value: "full", label: "full", description: "Classic caveman" },
+	{ value: "ultra", label: "ultra", description: "Maximum compression" },
+	{
+		value: "micro",
+		label: "micro",
+		description: "Experimental prompt-minimized mode",
+	},
+	{ value: "off", label: "off", description: "Disable caveman mode" },
+	{ value: "stop", label: "stop", description: "Disable caveman mode" },
+	{ value: "quit", label: "quit", description: "Disable caveman mode" },
+	{ value: "config", label: "config", description: "Open settings dialog" },
 ] as const;
 
 // ── Status labels ─────────────────────────────────────────────────────────────
 
 export const STATUS_LABELS: Record<Exclude<Level, "off">, string> = {
-	lite:           "LITE",
-	full:           "FULL",
-	ultra:          "ULTRA",
-	micro:          "MICRO",
+	lite: "LITE",
+	full: "FULL",
+	ultra: "ULTRA",
+	micro: "MICRO",
 };
 
 // ── Prompt fragments ──────────────────────────────────────────────────────────
@@ -174,7 +172,7 @@ export const DEFAULT_CONFIG: CavemanConfig = {
 	showStatus: true,
 };
 
-export const CONFIG_PATH = join(homedir(), ".pi", "agent", "caveman.json");
+const CONFIG_PATH = join(homedir(), ".pi", "agent", "caveman.json");
 
 export function parseConfig(raw: unknown): CavemanConfig {
 	const parsed = raw as Record<string, unknown>;
@@ -191,7 +189,7 @@ export function parseConfig(raw: unknown): CavemanConfig {
 
 let _saveQueue: Promise<void> = Promise.resolve();
 
-export async function loadConfig(): Promise<CavemanConfig> {
+async function loadConfig(): Promise<CavemanConfig> {
 	try {
 		const raw = await readFile(CONFIG_PATH, "utf8");
 		return parseConfig(JSON.parse(raw));
@@ -200,8 +198,8 @@ export async function loadConfig(): Promise<CavemanConfig> {
 	}
 }
 
-export async function saveConfig(config: CavemanConfig): Promise<void> {
-	const snapshot = JSON.stringify(config, null, 2) + "\n";
+async function saveConfig(config: CavemanConfig): Promise<void> {
+	const snapshot = `${JSON.stringify(config, null, 2)}\n`;
 	_saveQueue = _saveQueue.then(async () => {
 		await mkdir(join(homedir(), ".pi", "agent"), { recursive: true });
 		await writeFile(CONFIG_PATH, snapshot, "utf8");
@@ -211,7 +209,10 @@ export async function saveConfig(config: CavemanConfig): Promise<void> {
 
 // ── Pi extension ────────────────────────────────────────────────────────────
 
-export function caveman(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle {
+export function caveman(
+	pi: ExtensionAPI,
+	status: OptimizerStatus,
+): OptimizerHandle {
 	let level: Level = "off";
 	let config: CavemanConfig = { ...DEFAULT_CONFIG };
 	let configLoadPromise: Promise<void> | null = null;
@@ -240,7 +241,7 @@ export function caveman(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHan
 		const prompt = buildPrompt(level);
 		if (!prompt) return undefined;
 		const existing = event.systemPrompt ?? "";
-		return { systemPrompt: prompt + "\n\n" + existing };
+		return { systemPrompt: `${prompt}\n\n${existing}` };
 	});
 
 	// -- Restore state on session load --
@@ -265,13 +266,20 @@ export function caveman(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHan
 		syncStatus(ctx);
 	});
 
-	pi.on("agent_start", async (_event, ctx) => { syncStatus(ctx); });
-	pi.on("agent_end",   async (_event, ctx) => { syncStatus(ctx); });
+	pi.on("agent_start", async (_event, ctx) => {
+		syncStatus(ctx);
+	});
+	pi.on("agent_end", async (_event, ctx) => {
+		syncStatus(ctx);
+	});
 	pi.on("session_shutdown", async () => {});
 
 	// -- Subcommand handler (dispatched by the merged /opt router) --
 
-	async function run(args: string, ctx: ExtensionCommandContext): Promise<void> {
+	async function run(
+		args: string,
+		ctx: ExtensionCommandContext,
+	): Promise<void> {
 		const arg = args.trim().toLowerCase();
 
 		// No argument → show help
@@ -336,9 +344,19 @@ export function caveman(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHan
 			];
 
 			const container = new Container();
-			container.addChild(new Text(theme.fg("accent", theme.bold(" Caveman Config")), 0, 0));
-			container.addChild(new Text(theme.fg("dim", " Saved to ~/.pi/agent/caveman.json"), 0, 0));
-			container.addChild(new Text(theme.fg("dim", " Default level applies to future sessions."), 0, 0));
+			container.addChild(
+				new Text(theme.fg("accent", theme.bold(" Caveman Config")), 0, 0),
+			);
+			container.addChild(
+				new Text(theme.fg("dim", " Saved to ~/.pi/agent/caveman.json"), 0, 0),
+			);
+			container.addChild(
+				new Text(
+					theme.fg("dim", " Default level applies to future sessions."),
+					0,
+					0,
+				),
+			);
 			container.addChild(new Text("", 0, 0));
 
 			const applySettingChange = (id: string, newValue: string) => {
@@ -360,14 +378,23 @@ export function caveman(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHan
 			);
 
 			container.addChild(settingsList);
-			container.addChild(new Text(theme.fg("dim", " ←→/hl/tab change • ↑↓/jk move • esc close"), 0, 0));
+			container.addChild(
+				new Text(
+					theme.fg("dim", " ←→/hl/tab change • ↑↓/jk move • esc close"),
+					0,
+					0,
+				),
+			);
 
 			const cycleSelectedValue = (direction: -1 | 1) => {
-				const selectedIndex = (settingsList as unknown as { selectedIndex: number }).selectedIndex;
+				const selectedIndex = (
+					settingsList as unknown as { selectedIndex: number }
+				).selectedIndex;
 				const item = items[selectedIndex];
 				if (!item?.values?.length) return;
 				const currentIndex = item.values.indexOf(item.currentValue);
-				const nextIndex = (currentIndex + direction + item.values.length) % item.values.length;
+				const nextIndex =
+					(currentIndex + direction + item.values.length) % item.values.length;
 				const newValue = item.values[nextIndex]!;
 				item.currentValue = newValue;
 				settingsList.updateValue(item.id, newValue);
@@ -380,14 +407,29 @@ export function caveman(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHan
 				handleInput: (data: string) => {
 					if (data === "j") data = "\u001b[B";
 					else if (data === "k") data = "\u001b[A";
-					else if (data === "h") { cycleSelectedValue(-1); _tui.requestRender(); return; }
-					else if (data === "l" || data === "\u001b[C" || data === "\t") { cycleSelectedValue(1); _tui.requestRender(); return; }
-					else if (data === "\u001b[D") { cycleSelectedValue(-1); _tui.requestRender(); return; }
-					else if (data === "\u001b" || data === "q") { done(undefined); return; }
-
-					const result = settingsList.handleInput(data);
-					if (result === "done") done(undefined);
-					else _tui.requestRender();
+					else if (data === "h") {
+						cycleSelectedValue(-1);
+						_tui.requestRender();
+						return;
+					} else if (data === "l" || data === "\u001b[C" || data === "\t") {
+						cycleSelectedValue(1);
+						_tui.requestRender();
+						return;
+					} else if (data === "\u001b[D") {
+						cycleSelectedValue(-1);
+						_tui.requestRender();
+						return;
+					} else if (data === "\u001b" || data === "q") {
+						done(undefined);
+						return;
+					}
+
+					// SettingsList.handleInput now returns void; completion/cancel is
+					// signalled through the onChange/onCancel callbacks passed to the
+					// constructor (onCancel -> done(undefined)). Just forward input and
+					// re-render.
+					settingsList.handleInput(data);
+					_tui.requestRender();
 				},
 			};
 		});

package/src/index.ts

@@ -13,10 +13,15 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { caveman } from "./caveman.ts";
-import { rtk } from "./rtk.ts";
 import { json } from "./json.ts";
-import { OptimizerStatus, type OptimizerHandle, type OptimizerTool } from "./status.ts";
 import { registerOptCommand } from "./opt.ts";
+import { rtk } from "./rtk.ts";
+import {
+	type OptimizerHandle,
+	OptimizerStatus,
+	type OptimizerTool,
+} from "./status.ts";
+import { filterModelWarnings } from "./tool-result-filter.ts";
 
 export default function optimizer(pi: ExtensionAPI) {
 	const status = new OptimizerStatus();
@@ -30,4 +35,14 @@ export default function optimizer(pi: ExtensionAPI) {
 	};
 
 	registerOptCommand(pi, handles);
+
+	// Strip model-guidance warnings injected by pi-lens into tool_result content.
+	// These strings (BLIND WRITE, THRASHING) are directives for the LLM, not
+	// information for the user — filtering them here hides them from the TUI
+	// without affecting the model (it already acted on the write/edit result).
+	pi.on("tool_result", async (event) => {
+		const filtered = filterModelWarnings(event.content);
+		if (filtered === event.content) return undefined;
+		return { content: filtered };
+	});
 }

package/src/json.test.ts

@@ -1,8 +1,8 @@
-import { describe, it, expect } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import {
-	JSON_SYSTEM_PROMPT,
 	adviseToon,
 	isUniformObjectArray,
+	JSON_SYSTEM_PROMPT,
 	mentionsJson,
 	objectDepth,
 	skillDir,
@@ -72,9 +72,9 @@ describe("isUniformObjectArray", () => {
 	});
 
 	it("false for differing keys", () => {
-		expect(
-			isUniformObjectArray([{ id: 1 }, { id: 2, extra: true }]),
-		).toBe(false);
+		expect(isUniformObjectArray([{ id: 1 }, { id: 2, extra: true }])).toBe(
+			false,
+		);
 	});
 
 	it("false when a value is itself an object", () => {

package/src/json.ts

@@ -76,10 +76,7 @@ const JSON_TRIGGERS = [
 	"swagger",
 ] as const;
 
-const JSON_TRIGGER_RE = new RegExp(
-	`\\b(${JSON_TRIGGERS.join("|")})\\b`,
-	"i",
-);
+const JSON_TRIGGER_RE = new RegExp(`\\b(${JSON_TRIGGERS.join("|")})\\b`, "i");
 
 /**
  * True when the user prompt mentions JSON (or a related token), so the
@@ -120,7 +117,10 @@ export function adviseToon(value: unknown, maxDepth = 4): ToonAdvice {
 		}
 		// Array of arrays: TOON's only structurally-worse case.
 		if (value.every((v) => Array.isArray(v))) {
-			return { useToon: false, reason: "array of arrays — JSON is more compact" };
+			return {
+				useToon: false,
+				reason: "array of arrays — JSON is more compact",
+			};
 		}
 		// Uniform array of flat objects → tabular sweet spot.
 		if (isUniformObjectArray(value)) {
@@ -131,9 +131,15 @@ export function adviseToon(value: unknown, maxDepth = 4): ToonAdvice {
 		}
 		// Array of primitives.
 		if (value.every((v) => !isObjectLike(v))) {
-			return { useToon: true, reason: "primitive array — TOON omits quotes/braces" };
+			return {
+				useToon: true,
+				reason: "primitive array — TOON omits quotes/braces",
+			};
 		}
-		return { useToon: false, reason: "non-uniform array — savings uncertain, keep JSON" };
+		return {
+			useToon: false,
+			reason: "non-uniform array — savings uncertain, keep JSON",
+		};
 	}
 
 	if (isObjectLike(value)) {
@@ -144,7 +150,10 @@ export function adviseToon(value: unknown, maxDepth = 4): ToonAdvice {
 				reason: `nesting depth ${depth} > ${maxDepth} — compact JSON may win`,
 			};
 		}
-		return { useToon: true, reason: "shallow object — TOON drops quotes/braces" };
+		return {
+			useToon: true,
+			reason: "shallow object — TOON drops quotes/braces",
+		};
 	}
 
 	return { useToon: false, reason: "primitive value — nothing to compress" };
@@ -209,7 +218,10 @@ export function skillDir(): string {
 
 // ── Pi extension ──────────────────────────────────────────────────────────────
 
-export function json(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle {
+export function json(
+	pi: ExtensionAPI,
+	status: OptimizerStatus,
+): OptimizerHandle {
 	let enabled = true;
 
 	// Report into the shared optimizer indicator.
@@ -217,9 +229,15 @@ export function json(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 		status.set("toon", enabled, ctx);
 	}
 
-	pi.on("session_start", async (_event, ctx) => { syncStatus(ctx); });
-	pi.on("agent_start", async (_event, ctx) => { syncStatus(ctx); });
-	pi.on("agent_end", async (_event, ctx) => { syncStatus(ctx); });
+	pi.on("session_start", async (_event, ctx) => {
+		syncStatus(ctx);
+	});
+	pi.on("agent_start", async (_event, ctx) => {
+		syncStatus(ctx);
+	});
+	pi.on("agent_end", async (_event, ctx) => {
+		syncStatus(ctx);
+	});
 
 	// Surface the bundled skill so the model can load the full workflow.
 	pi.on("resources_discover", async () => {
@@ -234,7 +252,7 @@ export function json(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 		if (!enabled) return undefined;
 		if (!mentionsJson(event.prompt)) return undefined;
 		const existing = event.systemPrompt ?? "";
-		return { systemPrompt: JSON_SYSTEM_PROMPT + "\n\n" + existing };
+		return { systemPrompt: `${JSON_SYSTEM_PROMPT}\n\n${existing}` };
 	});
 
 	// -- Subcommand handler (dispatched by the merged /opt router) --
@@ -242,14 +260,21 @@ export function json(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 	function complete(prefix: string) {
 		const items = [
 			{ value: "on", label: "on", description: "Force JSON/TOON guidance on" },
-			{ value: "off", label: "off", description: "Force JSON/TOON guidance off" },
+			{
+				value: "off",
+				label: "off",
+				description: "Force JSON/TOON guidance off",
+			},
 		];
 		const n = prefix.trim().toLowerCase();
 		const filtered = items.filter((i) => i.value.startsWith(n));
 		return filtered.length > 0 ? filtered : null;
 	}
 
-	async function run(args: string, ctx: ExtensionCommandContext): Promise<void> {
+	async function run(
+		args: string,
+		ctx: ExtensionCommandContext,
+	): Promise<void> {
 		{
 			const arg = args.trim().toLowerCase();
 			if (arg === "on") enabled = true;

package/src/opt.test.ts

@@ -1,9 +1,5 @@
-import { describe, it, expect } from "bun:test";
-import {
-	parseInvocation,
-	completeInvocation,
-	buildOptHelp,
-} from "./opt.ts";
+import { describe, expect, it } from "bun:test";
+import { buildOptHelp, completeInvocation, parseInvocation } from "./opt.ts";
 import type { OptimizerHandle, OptimizerTool } from "./status.ts";
 
 /** Build a handle set with spy-able run/complete. */
@@ -88,6 +84,9 @@ describe("dispatch via run", () => {
 		const { name, rest } = parseInvocation("rtk off");
 		expect(name).toBe("rtk");
 		void handles[name as OptimizerTool].run(rest, {} as never);
-		expect(received).toBe("off");
+		// `received` is mutated inside the run() callback above; TS narrows it to
+		// `null` here since it can't see the side effect, so read it through an
+		// untyped cast before asserting.
+		expect(received as string | null).toBe("off");
 	});
 });

package/src/opt.ts

@@ -12,7 +12,11 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { CompletionItem, OptimizerHandle, OptimizerTool } from "./status.ts";
+import type {
+	CompletionItem,
+	OptimizerHandle,
+	OptimizerTool,
+} from "./status.ts";
 
 /** Split raw args into the subcommand name and the rest. */
 export function parseInvocation(args: string): { name: string; rest: string } {
@@ -38,7 +42,7 @@ export function completeInvocation(
 	handles: Record<OptimizerTool, OptimizerHandle>,
 ): CompletionItem[] | null {
 	// No space yet → still completing the tool name.
-	if (!/\s/.test(args.trimStart()) ) {
+	if (!/\s/.test(args.trimStart())) {
 		const prefix = args.trim().toLowerCase();
 		const names = (Object.keys(handles) as OptimizerTool[])
 			.filter((n) => n.startsWith(prefix))
@@ -58,11 +62,18 @@ export function completeInvocation(
 }
 
 /** Build the `/opt` help text listing every tool. */
-export function buildOptHelp(handles: Record<OptimizerTool, OptimizerHandle>): string {
+export function buildOptHelp(
+	handles: Record<OptimizerTool, OptimizerHandle>,
+): string {
 	const lines = (Object.keys(handles) as OptimizerTool[]).map(
 		(n) => `  /opt ${handles[n].help}`,
 	);
-	return ["pix-optimizer — token tools", "", "Usage: /opt <tool> [args]", ...lines].join("\n");
+	return [
+		"pix-optimizer — token tools",
+		"",
+		"Usage: /opt <tool> [args]",
+		...lines,
+	].join("\n");
 }
 
 export function registerOptCommand(
@@ -71,7 +82,8 @@ export function registerOptCommand(
 ): void {
 	pi.registerCommand("opt", {
 		description: "pix-optimizer: caveman / rtk / toon token tools",
-		getArgumentCompletions: (prefix: string) => completeInvocation(prefix, handles),
+		getArgumentCompletions: (prefix: string) =>
+			completeInvocation(prefix, handles),
 		handler: async (args, ctx) => {
 			const { name, rest } = parseInvocation(args ?? "");
 

package/src/rtk.test.ts

@@ -1,9 +1,11 @@
-import { describe, it, expect } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import {
-	splitChain,
-	rewriteChain,
 	applyRtkRewrite,
 	type BashCallEvent,
+	buildSudoBlockReason,
+	detectSudoSegments,
+	rewriteChain,
+	splitChain,
 } from "./rtk.ts";
 
 /** Build a fresh bash tool_call event for hook tests. */
@@ -105,13 +107,83 @@ describe("rewriteChain", () => {
 	});
 });
 
+// ── detectSudoSegments ───────────────────────────────────────────────────────
+
+describe("detectSudoSegments", () => {
+	it("returns empty for command with no sudo", () => {
+		expect(detectSudoSegments(["git status"])).toEqual([]);
+	});
+
+	it("detects a plain sudo segment", () => {
+		expect(detectSudoSegments(["sudo apt-get install foo"])).toEqual([
+			"sudo apt-get install foo",
+		]);
+	});
+
+	it("detects sudo in a chain (operators excluded)", () => {
+		const parts = ["git status ", "&&", " sudo make install"];
+		expect(detectSudoSegments(parts)).toEqual(["sudo make install"]);
+	});
+
+	it("detects multiple sudo segments", () => {
+		const parts = ["sudo rm -rf /tmp ", ";", " sudo reboot"];
+		expect(detectSudoSegments(parts)).toEqual([
+			"sudo rm -rf /tmp",
+			"sudo reboot",
+		]);
+	});
+
+	it("does not match 'sudoer' or 'pseudo'", () => {
+		expect(detectSudoSegments(["sudoers-check", "pseudo sudo"])).toEqual([]);
+	});
+
+	it("returns empty for operators-only parts", () => {
+		expect(detectSudoSegments(["&&", "||", ";"])).toEqual([]);
+	});
+});
+
+// ── buildSudoBlockReason ──────────────────────────────────────────────────────
+
+describe("buildSudoBlockReason", () => {
+	it("with sudo_run available: mentions sudo_run tool", () => {
+		const reason = buildSudoBlockReason(["sudo apt install curl"], true);
+		expect(reason).toContain("sudo_run");
+		expect(reason).toContain("sudo apt install curl");
+		expect(reason).not.toContain("not available");
+	});
+
+	it("with sudo_run available: instructs to strip sudo prefix", () => {
+		const reason = buildSudoBlockReason(["sudo make install"], true);
+		expect(reason).toContain("Strip the leading");
+	});
+
+	it("without sudo_run: explains restriction and asks user to run manually", () => {
+		const reason = buildSudoBlockReason(["sudo reboot"], false);
+		expect(reason).toContain("no sudo_run tool is available");
+		expect(reason).toContain("manually");
+		expect(reason).toContain("sudo reboot");
+	});
+
+	it("lists all blocked commands", () => {
+		const reason = buildSudoBlockReason(
+			["sudo rm -rf /tmp", "sudo reboot"],
+			true,
+		);
+		expect(reason).toContain("sudo rm -rf /tmp");
+		expect(reason).toContain("sudo reboot");
+	});
+});
+
 // Integration tests for the `tool_call` hook step. These guard the bug that
 // silently disabled rewriting: wrong event name + wrong field + wrong patch
 // mechanism. They assert on the IN-PLACE mutation contract the SDK requires.
 describe("applyRtkRewrite (tool_call hook step)", () => {
 	it("mutates event.input.command in place for a known bash command", () => {
 		const event = bashEvent("git status");
-		const changed = applyRtkRewrite(event, { enabled: true, rtkAvailable: true });
+		const changed = applyRtkRewrite(event, {
+			enabled: true,
+			rtkAvailable: true,
+		});
 		expect(changed).toBe(true);
 		expect(event.input.command).toBe("rtk git status");
 	});
@@ -124,49 +196,74 @@ describe("applyRtkRewrite (tool_call hook step)", () => {
 
 	it("does not mutate when disabled", () => {
 		const event = bashEvent("git status");
-		const changed = applyRtkRewrite(event, { enabled: false, rtkAvailable: true });
+		const changed = applyRtkRewrite(event, {
+			enabled: false,
+			rtkAvailable: true,
+		});
 		expect(changed).toBe(false);
 		expect(event.input.command).toBe("git status");
 	});
 
 	it("does not mutate when rtk binary is unavailable", () => {
 		const event = bashEvent("git status");
-		const changed = applyRtkRewrite(event, { enabled: true, rtkAvailable: false });
+		const changed = applyRtkRewrite(event, {
+			enabled: true,
+			rtkAvailable: false,
+		});
 		expect(changed).toBe(false);
 		expect(event.input.command).toBe("git status");
 	});
 
 	it("ignores non-bash tools", () => {
-		const event: BashCallEvent = { toolName: "grep", input: { command: "git status" } };
-		const changed = applyRtkRewrite(event, { enabled: true, rtkAvailable: true });
+		const event: BashCallEvent = {
+			toolName: "grep",
+			input: { command: "git status" },
+		};
+		const changed = applyRtkRewrite(event, {
+			enabled: true,
+			rtkAvailable: true,
+		});
 		expect(changed).toBe(false);
 		expect(event.input.command).toBe("git status");
 	});
 
 	it("leaves unknown commands untouched", () => {
 		const event = bashEvent("mkdir build && cd build");
-		const changed = applyRtkRewrite(event, { enabled: true, rtkAvailable: true });
+		const changed = applyRtkRewrite(event, {
+			enabled: true,
+			rtkAvailable: true,
+		});
 		expect(changed).toBe(false);
 		expect(event.input.command).toBe("mkdir build && cd build");
 	});
 
 	it("does not double-prefix an already-rtk command", () => {
 		const event = bashEvent("rtk git status");
-		const changed = applyRtkRewrite(event, { enabled: true, rtkAvailable: true });
+		const changed = applyRtkRewrite(event, {
+			enabled: true,
+			rtkAvailable: true,
+		});
 		expect(changed).toBe(false);
 		expect(event.input.command).toBe("rtk git status");
 	});
 
 	it("handles missing / non-string command safely", () => {
 		const event: BashCallEvent = { toolName: "bash", input: {} };
-		expect(applyRtkRewrite(event, { enabled: true, rtkAvailable: true })).toBe(false);
+		expect(applyRtkRewrite(event, { enabled: true, rtkAvailable: true })).toBe(
+			false,
+		);
 		const event2: BashCallEvent = { toolName: "bash", input: { command: 123 } };
-		expect(applyRtkRewrite(event2, { enabled: true, rtkAvailable: true })).toBe(false);
+		expect(applyRtkRewrite(event2, { enabled: true, rtkAvailable: true })).toBe(
+			false,
+		);
 	});
 
 	it("leaves command unchanged on unbalanced quotes", () => {
 		const event = bashEvent('git commit -m "oops');
-		const changed = applyRtkRewrite(event, { enabled: true, rtkAvailable: true });
+		const changed = applyRtkRewrite(event, {
+			enabled: true,
+			rtkAvailable: true,
+		});
 		expect(changed).toBe(false);
 		expect(event.input.command).toBe('git commit -m "oops');
 	});

package/src/rtk.ts

@@ -1,6 +1,6 @@
 /**
  * Simple RTK Integration
- * 
+ *
  * 1. Injects RTK system prompt (tells model to prefix commands with rtk)
  * 2. Rewrites bash commands to add rtk prefix when model forgets
  * 3. Falls back gracefully if rtk binary is missing
@@ -33,6 +33,46 @@ export interface BashCallEvent {
  * Extracted from the hook closure so the integration is directly testable
  * without a live ExtensionAPI.
  */
+/**
+ * Return the list of sudo sub-commands found in parsed chain segments.
+ * Each entry is the full segment body (trimmed) that starts with `sudo`.
+ * Operators are excluded. Returns empty array if none found.
+ */
+export function detectSudoSegments(parts: string[]): string[] {
+	return parts
+		.filter((p) => !CHAIN_OPERATORS.has(p.trim()))
+		.map((p) => p.trim())
+		.filter((p) => /^sudo\b/.test(p));
+}
+
+/**
+ * Build the block reason string shown to the model when a sudo command is
+ * intercepted. Directs the model to `sudo_run` when available, otherwise
+ * explains the restriction clearly.
+ */
+export function buildSudoBlockReason(
+	sudoCmds: string[],
+	hasSudoRunTool: boolean,
+): string {
+	const list = sudoCmds.map((c) => `  - ${c}`).join("\n");
+	if (hasSudoRunTool) {
+		return (
+			`bash cannot run sudo commands directly. ` +
+			`Use the \`sudo_run\` tool instead — it shows the user a confirmation dialog ` +
+			`and handles authentication securely.\n` +
+			`Blocked command(s):\n${list}\n` +
+			`Strip the leading \`sudo\` from the command and pass the rest to \`sudo_run\` ` +
+			`with a clear \`reason\` parameter.`
+		);
+	}
+	return (
+		`bash cannot run sudo commands in this session — ` +
+		`no sudo_run tool is available and direct sudo is not permitted.\n` +
+		`Blocked command(s):\n${list}\n` +
+		`Ask the user to run the command manually with elevated privileges.`
+	);
+}
+
 export function applyRtkRewrite(
 	event: BashCallEvent,
 	opts: { enabled: boolean; rtkAvailable: boolean },
@@ -62,13 +102,40 @@ RTK also has filtering subcommands the auto-rewriter won't add — reach for the
 
 // Commands that should be prefixed with rtk
 const RTK_COMMANDS = new Set([
-	"git", "gh", "ls", "tree", "find", "grep", "cat", "head", "tail",
-	"tsc", "lint", "eslint", "prettier", "next", "cargo", "rustc",
-	"vitest", "playwright", "jest", "test",
-	"pnpm", "npm", "npx", "yarn", "bun",
-	"docker", "kubectl", "aws", "psql",
-	"curl", "wget", "wc",
-	"prisma", "dotnet"
+	"git",
+	"gh",
+	"ls",
+	"tree",
+	"find",
+	"grep",
+	"cat",
+	"head",
+	"tail",
+	"tsc",
+	"lint",
+	"eslint",
+	"prettier",
+	"next",
+	"cargo",
+	"rustc",
+	"vitest",
+	"playwright",
+	"jest",
+	"test",
+	"pnpm",
+	"npm",
+	"npx",
+	"yarn",
+	"bun",
+	"docker",
+	"kubectl",
+	"aws",
+	"psql",
+	"curl",
+	"wget",
+	"wc",
+	"prisma",
+	"dotnet",
 ]);
 
 interface RtkStatus {
@@ -159,10 +226,16 @@ export function rewriteChain(command: string): string {
 	return changed ? rewritten.join("") : command;
 }
 
-export function rtk(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle {
+export function rtk(
+	pi: ExtensionAPI,
+	status: OptimizerStatus,
+): OptimizerHandle {
 	let rtkStatus: RtkStatus | null = null;
 	let warnedMissing = false;
 	let enabled = true;
+	// Tracks whether pix-sudo's sudo_run tool is active this session.
+	// Set from before_agent_start selectedTools; defaults to false until known.
+	let hasSudoRunTool = false;
 
 	// Report into the shared optimizer indicator. RTK counts as "on" only when
 	// enabled AND the binary is actually available.
@@ -183,27 +256,31 @@ export function rtk(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 				rtkStatus = {
 					available: true,
 					checkedAt: Date.now(),
-					path: result.stdout.trim()
+					path: result.stdout.trim(),
 				};
 				warnedMissing = false;
 				return rtkStatus;
 			}
-		} catch (error) {
+		} catch (_error) {
 			// which command failed
 		}
 
 		rtkStatus = {
 			available: false,
-			checkedAt: Date.now()
+			checkedAt: Date.now(),
 		};
 		return rtkStatus;
 	};
 
-	// Inject RTK system prompt
+	// Inject RTK system prompt + detect sudo_run tool availability.
 	pi.on("before_agent_start", async (event) => {
+		// Detect sudo_run from the active tool list for this session.
+		const tools: string[] = event.systemPromptOptions?.selectedTools ?? [];
+		hasSudoRunTool = tools.includes("sudo_run");
+
 		if (!enabled) return undefined;
 		const existing = event.systemPrompt ?? "";
-		return { systemPrompt: RTK_SYSTEM_PROMPT + "\n\n" + existing };
+		return { systemPrompt: `${RTK_SYSTEM_PROMPT}\n\n${existing}` };
 	});
 
 	// Keep the status indicator in sync across the agent lifecycle. Probe
@@ -212,12 +289,19 @@ export function rtk(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 		await checkRtkAvailability();
 		syncStatus(ctx);
 	});
-	pi.on("agent_start", async (_event, ctx) => { syncStatus(ctx); });
-	pi.on("agent_end", async (_event, ctx) => { syncStatus(ctx); });
+	pi.on("agent_start", async (_event, ctx) => {
+		syncStatus(ctx);
+	});
+	pi.on("agent_end", async (_event, ctx) => {
+		syncStatus(ctx);
+	});
 
 	// -- Subcommand handler (dispatched by the merged /opt router) --
 
-	async function run(args: string, ctx: ExtensionCommandContext): Promise<void> {
+	async function run(
+		args: string,
+		ctx: ExtensionCommandContext,
+	): Promise<void> {
 		const arg = args.trim().toLowerCase();
 		if (arg === "on") enabled = true;
 		else if (arg === "off") enabled = false;
@@ -259,7 +343,7 @@ export function rtk(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 			if (!warnedMissing) {
 				ctx.ui.notify(
 					"RTK binary not found. Install: cargo install rtk-ai",
-					"warning"
+					"warning",
 				);
 				warnedMissing = true;
 			}
@@ -269,6 +353,20 @@ export function rtk(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle
 		// First confirmed-available probe may have flipped state — refresh icon.
 		syncStatus(ctx);
 
+		// Block sudo segments before rtk rewriting.
+		// splitChain is safe to call here — same parser used by rewriteChain.
+		const command = event.input?.command;
+		if (typeof command === "string" && command) {
+			const parts = splitChain(command);
+			if (parts) {
+				const sudoCmds = detectSudoSegments(parts);
+				if (sudoCmds.length > 0) {
+					const reason = buildSudoBlockReason(sudoCmds, hasSudoRunTool);
+					return { block: true, reason };
+				}
+			}
+		}
+
 		// Rewrite every segment in the command chain that uses a known RTK
 		// command (e.g. `git add . && git push` -> `rtk git add . && rtk git push`).
 		// Mutates `event.input.command` in place — the SDK's supported patch path.

package/src/status.test.ts

@@ -1,9 +1,9 @@
-import { describe, it, expect } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import {
 	OptimizerStatus,
+	renderStatus,
 	STATUS_KEY,
 	TOOL_ICONS,
-	renderStatus,
 } from "./status.ts";
 
 /** Tagging colorizer: <accent>X</accent> / <dim>X</dim> for assertions. */

package/src/status.ts

@@ -53,12 +53,12 @@ export const TOOL_ICONS: Record<OptimizerTool, string> = {
 };
 
 /** Fixed left-to-right order of icons in the cell. */
-export const TOOL_ORDER: readonly OptimizerTool[] = ["caveman", "rtk", "toon"];
+const TOOL_ORDER: readonly OptimizerTool[] = ["caveman", "rtk", "toon"];
 
 /** Theme color for enabled icons. */
-export const ENABLED_COLOR: ThemeColor = "accent";
+const ENABLED_COLOR: ThemeColor = "accent";
 /** Theme color for disabled icons. */
-export const DISABLED_COLOR: ThemeColor = "dim";
+const DISABLED_COLOR: ThemeColor = "dim";
 
 /** Colorizer: maps a (theme color, text) pair to a rendered string. */
 export type Colorize = (color: ThemeColor, text: string) => string;
@@ -89,7 +89,11 @@ export class OptimizerStatus {
 	private states: Partial<Record<OptimizerTool, boolean>> = {};
 
 	/** Update one tool's enabled state and repaint the shared cell. */
-	set(tool: OptimizerTool, enabled: boolean, ctx: Pick<ExtensionContext, "ui">): void {
+	set(
+		tool: OptimizerTool,
+		enabled: boolean,
+		ctx: Pick<ExtensionContext, "ui">,
+	): void {
 		this.states[tool] = enabled;
 		this.paint(ctx);
 	}

package/src/tool-result-filter.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "bun:test";
+import {
+	filterModelWarnings,
+	stripModelWarningParagraphs,
+} from "./tool-result-filter.ts";
+
+// ── stripModelWarningParagraphs ───────────────────────────────────────────────
+
+describe("stripModelWarningParagraphs", () => {
+	it("passes through text with no warnings", () => {
+		const text = "Exit code: 0\n\nsome output here";
+		expect(stripModelWarningParagraphs(text)).toBe(text);
+	});
+
+	it("strips a BLIND WRITE paragraph", () => {
+		const text =
+			"Exit code: 0\n\nsome output\n\n⚠ BLIND WRITE — editing `foo.ts` without reading in the last 5 tool calls. Read the file first to avoid assumptions.";
+		const result = stripModelWarningParagraphs(text);
+		expect(result).not.toContain("BLIND WRITE");
+		expect(result).toContain("some output");
+	});
+
+	it("strips a THRASHING paragraph", () => {
+		const text =
+			"ok\n\n🔴 THRASHING — 3 consecutive `edit` calls on foo.ts. Consider reading first.";
+		const result = stripModelWarningParagraphs(text);
+		expect(result).not.toContain("THRASHING");
+		expect(result).toContain("ok");
+	});
+
+	it("strips multiple warning paragraphs", () => {
+		const text =
+			"output\n\n⚠ BLIND WRITE — foo\n\n🔴 THRASHING — bar\n\nmore output";
+		const result = stripModelWarningParagraphs(text);
+		expect(result).not.toContain("BLIND WRITE");
+		expect(result).not.toContain("THRASHING");
+		expect(result).toContain("output");
+		expect(result).toContain("more output");
+	});
+
+	it("returns original reference when nothing stripped", () => {
+		const text = "no warnings here";
+		expect(stripModelWarningParagraphs(text)).toBe(text);
+	});
+
+	it("trims trailing whitespace after stripping", () => {
+		const text = "output\n\n⚠ BLIND WRITE — foo";
+		const result = stripModelWarningParagraphs(text);
+		expect(result).toBe("output");
+	});
+
+	it("does not strip mid-paragraph BLIND WRITE mentions", () => {
+		// Only strips when the paragraph *starts* with the prefix
+		const text = "The BLIND WRITE check is a feature.\n\nsome output";
+		expect(stripModelWarningParagraphs(text)).toBe(text);
+	});
+});
+
+// ── filterModelWarnings ───────────────────────────────────────────────────────
+
+describe("filterModelWarnings", () => {
+	it("returns original array when no warnings present", () => {
+		const content = [{ type: "text" as const, text: "clean output" }];
+		expect(filterModelWarnings(content)).toBe(content);
+	});
+
+	it("filters BLIND WRITE from text block", () => {
+		const content = [
+			{
+				type: "text" as const,
+				text: "Exit code: 0\n\nok\n\n⚠ BLIND WRITE — editing `x.ts` without reading.",
+			},
+		];
+		const result = filterModelWarnings(content);
+		expect(result).not.toBe(content);
+		expect(result[0]?.type).toBe("text");
+		if (result[0]?.type === "text") {
+			expect((result[0] as { type: string; text: string }).text).not.toContain(
+				"BLIND WRITE",
+			);
+		}
+	});
+
+	it("leaves image blocks untouched", () => {
+		const img = { type: "image", source: { type: "base64", data: "abc" } };
+		const content = [img] as never[];
+		expect(filterModelWarnings(content)).toBe(content);
+	});
+
+	it("only modifies affected blocks, keeps others by reference", () => {
+		const clean = { type: "text" as const, text: "clean" };
+		const dirty = {
+			type: "text" as const,
+			text: "output\n\n⚠ BLIND WRITE — foo",
+		};
+		const content = [clean, dirty];
+		const result = filterModelWarnings(content);
+		// The array is new but clean block is the same reference
+		expect(result[0]).toBe(clean);
+		expect(result[1]).not.toBe(dirty);
+	});
+});

package/src/tool-result-filter.ts

@@ -0,0 +1,56 @@
+/**
+ * tool-result-filter.ts — strip model-guidance text from tool_result content.
+ *
+ * pi-lens appends diagnostic strings (BLIND WRITE, THRASHING) to tool_result
+ * content as guidance for the LLM. These are not useful to the user and clutter
+ * the TUI. This module filters them out of content blocks before they render.
+ *
+ * Patterns are anchored to the start of a paragraph (preceded by \n\n) so we
+ * don't accidentally clip real output that happens to contain these strings.
+ */
+
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+
+export type ToolContent = TextContent | ImageContent;
+
+/**
+ * Paragraph prefixes that identify model-only guidance injected by pi-lens.
+ * Each pattern matches from the start of a \n\n-delimited paragraph.
+ */
+const MODEL_WARNING_PREFIXES = ["⚠ BLIND WRITE —", "🔴 THRASHING —"] as const;
+
+/**
+ * Strip model-guidance paragraphs from a single text block's content.
+ * Returns the original string if nothing was removed.
+ */
+export function stripModelWarningParagraphs(text: string): string {
+	// Split on double-newline paragraph boundaries, filter out guidance paragraphs,
+	// then rejoin. Trim trailing whitespace from the result.
+	const paragraphs = text.split(/\n\n/);
+	const kept = paragraphs.filter(
+		(p) =>
+			!MODEL_WARNING_PREFIXES.some((prefix) =>
+				p.trimStart().startsWith(prefix),
+			),
+	);
+	if (kept.length === paragraphs.length) return text;
+	return kept.join("\n\n").trimEnd();
+}
+
+/**
+ * Filter model-guidance warnings from an array of tool content blocks.
+ * Returns the original array reference if no blocks were modified.
+ */
+export function filterModelWarnings(content: ToolContent[]): ToolContent[] {
+	let changed = false;
+	const result = content.map((block) => {
+		if (block.type !== "text") return block;
+		const text = (block as TextContent).text;
+		if (typeof text !== "string") return block;
+		const filtered = stripModelWarningParagraphs(text);
+		if (filtered === text) return block;
+		changed = true;
+		return { ...block, text: filtered } as TextContent;
+	});
+	return changed ? result : content;
+}