gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1594b263e

package/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.test.ts

@@ -1,7 +1,151 @@
+// GSD2 — Tests for input-controller image pasting behavior
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { describe, it, beforeEach } from "node:test";
 import assert from "node:assert/strict";
 import test from "node:test";
-
 import { setupEditorSubmitHandler } from "./input-controller.js";
+import { ContextualTips } from "../../../core/contextual-tips.js";
+import type { InteractiveModeStateHost } from "../interactive-mode-state.js";
+import type { ImageContent } from "@gsd/pi-ai";
+
+/** Minimal mock host satisfying InteractiveModeStateHost + setupEditorSubmitHandler extras. */
+function createMockHost() {
+	const promptCalls: Array<{ text: string; options?: any }> = [];
+	const historyCalls: string[] = [];
+	let editorText = "";
+
+	const host = {
+		defaultEditor: {
+			onSubmit: undefined as ((text: string) => Promise<void>) | undefined,
+			addToHistory: (text: string) => { historyCalls.push(text); },
+			setText: (text: string) => { editorText = text; },
+			getText: () => editorText,
+		},
+		editor: {
+			setText: (text: string) => { editorText = text; },
+			getText: () => editorText,
+			addToHistory: (text: string) => { historyCalls.push(text); },
+		},
+		session: {
+			isStreaming: false,
+			isCompacting: false,
+			isBashRunning: false,
+			thinkingLevel: undefined,
+			prompt: async (text: string, options?: any) => { promptCalls.push({ text, options }); },
+		},
+		ui: { requestRender: () => {} },
+		footer: {},
+		keybindings: {},
+		statusContainer: {},
+		chatContainer: {},
+		pinnedMessageContainer: {},
+		settingsManager: {},
+		pendingTools: new Map(),
+		toolOutputExpanded: false,
+		hideThinkingBlock: false,
+		isBashMode: false,
+		onInputCallback: undefined,
+		isInitialized: true,
+		loadingAnimation: undefined,
+		pendingWorkingMessage: undefined,
+		defaultWorkingMessage: "Working...",
+		streamingComponent: undefined,
+		streamingMessage: undefined,
+		retryEscapeHandler: undefined,
+		retryLoader: undefined,
+		autoCompactionLoader: undefined,
+		autoCompactionEscapeHandler: undefined,
+		compactionQueuedMessages: [] as Array<{ text: string; mode: "steer" | "followUp" }>,
+		extensionSelector: undefined,
+		extensionInput: undefined,
+		extensionEditor: undefined,
+		editorContainer: {},
+		keybindingsManager: undefined,
+		pendingImages: [] as ImageContent[],
+
+		// Extra methods required by setupEditorSubmitHandler
+		getSlashCommandContext: () => ({}),
+		handleBashCommand: async (_command: string, _excludeFromContext?: boolean) => {},
+		showWarning: (_message: string) => {},
+		showError: (_message: string) => {},
+		showTip: (_message: string) => {},
+		updateEditorBorderColor: () => {},
+		isExtensionCommand: (_text: string) => false,
+		isKnownSlashCommand: (_text: string) => false,
+		queueCompactionMessage: (_text: string, _mode: "steer" | "followUp") => {},
+		updatePendingMessagesDisplay: () => {},
+		flushPendingBashComponents: () => {},
+		contextualTips: new ContextualTips(),
+		getContextPercent: () => undefined,
+		options: { submitPromptsDirectly: true },
+	} satisfies InteractiveModeStateHost & Parameters<typeof setupEditorSubmitHandler>[0];
+
+	return { host, promptCalls, historyCalls };
+}
+
+const TEST_IMAGE: ImageContent = {
+	type: "image",
+	data: "iVBORw0KGgo=",
+	mimeType: "image/png",
+};
+
+describe("input-controller pending images", () => {
+	let host: ReturnType<typeof createMockHost>["host"];
+	let promptCalls: ReturnType<typeof createMockHost>["promptCalls"];
+
+	beforeEach(() => {
+		const mock = createMockHost();
+		host = mock.host;
+		promptCalls = mock.promptCalls;
+		setupEditorSubmitHandler(host);
+	});
+
+	it("passes pending images to session.prompt on submit", async () => {
+		host.pendingImages.push({ ...TEST_IMAGE });
+		await host.defaultEditor.onSubmit!("describe this image");
+
+		assert.equal(promptCalls.length, 1);
+		assert.equal(promptCalls[0].text, "describe this image");
+		assert.ok(promptCalls[0].options?.images);
+		assert.equal(promptCalls[0].options.images.length, 1);
+		assert.equal(promptCalls[0].options.images[0].mimeType, "image/png");
+	});
+
+	it("clears pending images after submit", async () => {
+		host.pendingImages.push({ ...TEST_IMAGE });
+		await host.defaultEditor.onSubmit!("describe this image");
+
+		assert.equal(host.pendingImages.length, 0);
+	});
+
+	it("passes undefined images when no images are pending", async () => {
+		await host.defaultEditor.onSubmit!("hello");
+
+		assert.equal(promptCalls.length, 1);
+		assert.equal(promptCalls[0].options?.images, undefined);
+	});
+
+	it("passes multiple images in order", async () => {
+		const img1: ImageContent = { type: "image", data: "aaa=", mimeType: "image/png" };
+		const img2: ImageContent = { type: "image", data: "bbb=", mimeType: "image/jpeg" };
+		host.pendingImages.push(img1, img2);
+
+		await host.defaultEditor.onSubmit!("describe these images");
+
+		assert.equal(promptCalls[0].options.images.length, 2);
+		assert.equal(promptCalls[0].options.images[0].data, "aaa=");
+		assert.equal(promptCalls[0].options.images[1].data, "bbb=");
+	});
+
+	it("discards pending images on bash command", async () => {
+		host.pendingImages.push({ ...TEST_IMAGE });
+		await host.defaultEditor.onSubmit!("! ls -la");
+
+		assert.equal(host.pendingImages.length, 0);
+		assert.equal(promptCalls.length, 0); // bash commands don't go through prompt
+	});
+});
 
 type HostOptions = {
 	knownSlashCommands?: string[];
@@ -17,6 +161,7 @@ function createHost(options: HostOptions = {}) {
 	const prompted: string[] = [];
 	const errors: string[] = [];
 	const warnings: string[] = [];
+	const tips: string[] = [];
 	const history: string[] = [];
 	const knownSlashCommands = new Set(options.knownSlashCommands ?? []);
 	let editorText = "";
@@ -48,6 +193,7 @@ function createHost(options: HostOptions = {}) {
 		ui: {
 			requestRender() {},
 		},
+		pendingImages: [] as ImageContent[],
 		getSlashCommandContext: () => ({
 			showSettingsSelector: () => {
 				settingsOpened += 1;
@@ -60,6 +206,9 @@ function createHost(options: HostOptions = {}) {
 		showError(message: string) {
 			errors.push(message);
 		},
+		showTip(message: string) {
+			tips.push(message);
+		},
 		updateEditorBorderColor() {},
 		isExtensionCommand() {
 			return false;
@@ -70,6 +219,15 @@ function createHost(options: HostOptions = {}) {
 		queueCompactionMessage() {},
 		updatePendingMessagesDisplay() {},
 		flushPendingBashComponents() {},
+		contextualTips: {
+			recordBashIncluded() {},
+			evaluate() {
+				return undefined;
+			},
+		},
+		getContextPercent() {
+			return undefined;
+		},
 	};
 
 	setupEditorSubmitHandler(host as any);
@@ -79,6 +237,7 @@ function createHost(options: HostOptions = {}) {
 		prompted,
 		errors,
 		warnings,
+		tips,
 		history,
 		getEditorText: () => editorText,
 		getSettingsOpened: () => settingsOpened,

package/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.ts

@@ -1,7 +1,19 @@
+import type { ImageContent } from "@gsd/pi-ai";
 import { dispatchSlashCommand } from "../slash-command-handlers.js";
 import type { InteractiveModeStateHost } from "../interactive-mode-state.js";
 import type { ContextualTips } from "../../../core/contextual-tips.js";
 
+/**
+ * Consume and clear any pending pasted images from the host.
+ * Returns undefined if there are no pending images.
+ */
+function consumePendingImages(host: InteractiveModeStateHost): ImageContent[] | undefined {
+	if (host.pendingImages.length === 0) return undefined;
+	const images = [...host.pendingImages];
+	host.pendingImages.length = 0;
+	return images;
+}
+
 export function setupEditorSubmitHandler(host: InteractiveModeStateHost & {
 	getSlashCommandContext: () => any;
 	handleBashCommand: (command: string, excludeFromContext?: boolean) => Promise<void>;
@@ -26,6 +38,7 @@ export function setupEditorSubmitHandler(host: InteractiveModeStateHost & {
 			const handled = await dispatchSlashCommand(text, host.getSlashCommandContext());
 			if (handled) {
 				host.editor.setText("");
+				consumePendingImages(host); // discard images on slash command
 				return;
 			}
 			if (!host.isKnownSlashCommand(text)) {
@@ -53,10 +66,14 @@ export function setupEditorSubmitHandler(host: InteractiveModeStateHost & {
 				await host.handleBashCommand(command, isExcluded);
 				host.isBashMode = false;
 				host.updateEditorBorderColor();
+				consumePendingImages(host); // discard images on bash command
 				return;
 			}
 		}
 
+		// Consume pending images for prompt submissions
+		const images = consumePendingImages(host);
+
 		// Evaluate contextual tips before sending to agent
 		const tip = host.contextualTips.evaluate({
 			input: text,
@@ -73,7 +90,7 @@ export function setupEditorSubmitHandler(host: InteractiveModeStateHost & {
 				host.editor.addToHistory?.(text);
 				host.editor.setText("");
 				try {
-					await host.session.prompt(text);
+					await host.session.prompt(text, { images });
 				} catch (error: unknown) {
 					const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
 					host.showError(errorMessage);
@@ -87,7 +104,7 @@ export function setupEditorSubmitHandler(host: InteractiveModeStateHost & {
 		if (host.session.isStreaming) {
 			host.editor.addToHistory?.(text);
 			host.editor.setText("");
-			await host.session.prompt(text, { streamingBehavior: "steer" });
+			await host.session.prompt(text, { streamingBehavior: "steer", images });
 			host.updatePendingMessagesDisplay();
 			host.ui.requestRender();
 			return;
@@ -104,7 +121,7 @@ export function setupEditorSubmitHandler(host: InteractiveModeStateHost & {
 		if (host.options?.submitPromptsDirectly) {
 			host.editor.addToHistory?.(text);
 			try {
-				await host.session.prompt(text);
+				await host.session.prompt(text, { images });
 			} catch (error: unknown) {
 				const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
 				host.showError(errorMessage);

package/packages/pi-coding-agent/src/modes/interactive/interactive-mode-state.ts

@@ -1,3 +1,4 @@
+import type { ImageContent } from "@gsd/pi-ai";
 import type { AgentSessionEvent } from "../../core/agent-session.js";
 
 export interface InteractiveModeStateHost {
@@ -32,6 +33,7 @@ export interface InteractiveModeStateHost {
 	extensionEditor?: any;
 	editorContainer: any;
 	keybindingsManager?: any;
+	pendingImages: ImageContent[];
 }
 
 export type InteractiveModeEvent = AgentSessionEvent;

package/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts

@@ -3,7 +3,6 @@
  * Handles TUI rendering and user interaction, delegating business logic to AgentSession.
  */
 
-import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -62,7 +61,7 @@ import { type SessionContext, SessionManager } from "../../core/session-manager.
 import { BUILTIN_SLASH_COMMANDS } from "../../core/slash-commands.js";
 import type { TruncationResult } from "../../core/tools/truncate.js";
 import { getChangelogPath, getNewEntries, parseChangelog } from "../../utils/changelog.js";
-import { extensionForImageMimeType, readClipboardImage } from "../../utils/clipboard-image.js";
+import { readClipboardImage } from "../../utils/clipboard-image.js";
 import { ensureTool } from "../../utils/tools-manager.js";
 import { AssistantMessageComponent } from "./components/assistant-message.js";
 import { BashExecutionComponent } from "./components/bash-execution.js";
@@ -240,6 +239,9 @@ export class InteractiveMode {
 	// Tool output expansion state
 	private toolOutputExpanded = false;
 
+	// Pasted image tracking
+	private pendingImages: ImageContent[] = [];
+
 	// Thinking block visibility state
 	private hideThinkingBlock = false;
 
@@ -648,8 +650,10 @@ export class InteractiveMode {
 		// Main interactive loop
 		while (true) {
 			const userInput = await this.getUserInput();
+			const images = this.pendingImages.length > 0 ? [...this.pendingImages] : undefined;
+			this.pendingImages.length = 0;
 			try {
-				await this.session.prompt(userInput);
+				await this.session.prompt(userInput, { images });
 			} catch (error: unknown) {
 				const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
 				this.showError(errorMessage);
@@ -1814,6 +1818,13 @@ export class InteractiveMode {
 			this.editor = this.defaultEditor;
 		}
 
+		// Ensure pasted image path handler is set on the active editor
+		if (!this.editor.onPasteImagePath) {
+			this.editor.onPasteImagePath = (filePath: string) => {
+				this.handlePastedImagePath(filePath);
+			};
+		}
+
 		this.editorContainer.addChild(this.editor as Component);
 		this.ui.setFocus(this.editor as Component);
 		this.ui.requestRender();
@@ -1948,6 +1959,7 @@ export class InteractiveMode {
 				this.session.abortBash();
 			} else if (this.isBashMode) {
 				this.editor.setText("");
+				this.pendingImages.length = 0;
 				this.isBashMode = false;
 				this.updateEditorBorderColor();
 			} else if (!this.editor.getText().trim()) {
@@ -2002,6 +2014,12 @@ export class InteractiveMode {
 		this.defaultEditor.onPasteImage = () => {
 			this.handleClipboardImagePaste();
 		};
+
+		// Handle image file paths pasted via terminal emulator (e.g. iTerm2).
+		// Set on defaultEditor here; setCustomEditorComponent guards re-assignment for custom editors.
+		this.defaultEditor.onPasteImagePath = (filePath: string) => {
+			this.handlePastedImagePath(filePath);
+		};
 	}
 
 	private async handleClipboardImagePaste(): Promise<void> {
@@ -2011,21 +2029,104 @@ export class InteractiveMode {
 				return;
 			}
 
-			// Write to temp file
-			const tmpDir = os.tmpdir();
-			const ext = extensionForImageMimeType(image.mimeType) ?? "png";
-			const fileName = `pi-clipboard-${crypto.randomUUID()}.${ext}`;
-			const filePath = path.join(tmpDir, fileName);
-			fs.writeFileSync(filePath, Buffer.from(image.bytes));
+			// Store image as base64 ImageContent for sending with the prompt
+			const imageContent: ImageContent = {
+				type: "image",
+				data: Buffer.from(image.bytes).toString("base64"),
+				mimeType: image.mimeType,
+			};
+			this.pendingImages.push(imageContent);
 
-			// Insert file path directly
-			this.editor.insertTextAtCursor?.(filePath);
+			// Insert friendly placeholder instead of file path
+			const imageNum = this.pendingImages.length;
+			this.editor.insertTextAtCursor?.(`[Image #${imageNum}]`);
 			this.ui.requestRender();
 		} catch {
 			// Silently ignore clipboard errors (may not have permission, etc.)
 		}
 	}
 
+	// MIME types restricted to formats commonly accepted by AI vision APIs.
+	// SVG is excluded — it is XML/JS-bearing and not safe to forward as image content.
+	// TIFF/HEIC/HEIF/AVIF are excluded for compatibility; users can convert before pasting.
+	private static readonly MIME_BY_EXT: Record<string, string> = {
+		png: "image/png",
+		jpg: "image/jpeg",
+		jpeg: "image/jpeg",
+		gif: "image/gif",
+		webp: "image/webp",
+	};
+
+	// Magic-byte signatures used to verify file content matches its extension,
+	// preventing arbitrary-file-read via crafted paste of e.g. "/etc/passwd.png".
+	private static matchesImageSignature(buf: Buffer, mimeType: string): boolean {
+		if (buf.length < 12) return false;
+		switch (mimeType) {
+			case "image/png":
+				return buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47;
+			case "image/jpeg":
+				return buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff;
+			case "image/gif":
+				return (
+					buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38 &&
+					(buf[4] === 0x37 || buf[4] === 0x39) && buf[5] === 0x61
+				);
+			case "image/webp":
+				return (
+					buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
+					buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50
+				);
+			default:
+				return false;
+		}
+	}
+
+	private handlePastedImagePath(filePath: string): void {
+		try {
+			const ext = path.extname(filePath).slice(1).toLowerCase();
+			const mimeType = InteractiveMode.MIME_BY_EXT[ext];
+			if (!mimeType) {
+				// Unsupported / unsafe extension — fall back to inserting raw path.
+				this.editor.insertTextAtCursor?.(filePath);
+				this.ui.requestRender();
+				return;
+			}
+
+			// Reject symlinks to prevent reading sensitive files via a symlinked
+			// `.png` that points at e.g. ~/.ssh/id_rsa.
+			const lst = fs.lstatSync(filePath);
+			if (!lst.isFile()) {
+				this.editor.insertTextAtCursor?.(filePath);
+				this.ui.requestRender();
+				return;
+			}
+
+			const data = fs.readFileSync(filePath);
+
+			// Magic-byte check — confirms file content actually matches the
+			// extension before we forward bytes to a model.
+			if (!InteractiveMode.matchesImageSignature(data, mimeType)) {
+				this.editor.insertTextAtCursor?.(filePath);
+				this.ui.requestRender();
+				return;
+			}
+
+			this.pendingImages.push({
+				type: "image",
+				data: data.toString("base64"),
+				mimeType,
+			});
+
+			const imageNum = this.pendingImages.length;
+			this.editor.insertTextAtCursor?.(`[Image #${imageNum}]`);
+			this.ui.requestRender();
+		} catch {
+			// Fall back to inserting the raw path if file can't be read
+			this.editor.insertTextAtCursor?.(filePath);
+			this.ui.requestRender();
+		}
+	}
+
 	private getSlashCommandContext(): SlashCommandContext {
 		return {
 			session: this.session,
@@ -2562,12 +2663,16 @@ export class InteractiveMode {
 			return;
 		}
 
+		// Consume pending images
+		const images = this.pendingImages.length > 0 ? [...this.pendingImages] : undefined;
+		this.pendingImages.length = 0;
+
 		// Queue input during compaction (extension commands execute immediately)
 		if (this.session.isCompacting) {
 			if (this.isExtensionCommand(text)) {
 				this.editor.addToHistory?.(text);
 				this.editor.setText("");
-				await this.session.prompt(text);
+				await this.session.prompt(text, { images });
 			} else {
 				this.queueCompactionMessage(text, "followUp");
 			}
@@ -2579,7 +2684,7 @@ export class InteractiveMode {
 		if (this.session.isStreaming) {
 			this.editor.addToHistory?.(text);
 			this.editor.setText("");
-			await this.session.prompt(text, { streamingBehavior: "followUp" });
+			await this.session.prompt(text, { streamingBehavior: "followUp", images });
 			this.updatePendingMessagesDisplay();
 			this.ui.requestRender();
 		}
@@ -3585,7 +3690,19 @@ export class InteractiveMode {
 					this.ui.requestRender();
 				},
 				async (provider: string) => {
-					// Enter key → auth setup for selected provider (#3579)
+					// Enter key → auth setup for selected provider (#3579).
+					// Only OAuth providers support the login dialog flow.
+					// externalCli providers (e.g. claude-code) authenticate through
+					// their own CLI — sending them to the OAuth dialog produces
+					// "Unknown OAuth provider: claude-code" (#4548).
+					const isOAuthProvider = this.session.modelRegistry.authStorage
+						.getOAuthProviders()
+						.some((p) => p.id === provider);
+					if (!isOAuthProvider) {
+						done();
+						this.showStatus(`${provider} uses external CLI auth — use /model to select a model or run the provider's own auth command.`);
+						return;
+					}
 					done();
 					await this.showLoginDialog(provider);
 				},
@@ -3851,6 +3968,7 @@ export class InteractiveMode {
 		this.streamingComponent = undefined;
 		this.streamingMessage = undefined;
 		this.pendingTools.clear();
+		this.pendingImages.length = 0;
 
 		// Reset contextual tips for the new session
 		this.contextualTips.reset();

package/packages/pi-coding-agent/src/tests/system-prompt-skill-filter.test.ts

@@ -0,0 +1,157 @@
+// @gsd/pi-coding-agent + system-prompt-skill-filter.test — coverage for the
+// optional `skillFilter` option added to buildSystemPrompt (RFC #4779). The
+// filter lets consumers narrow the <available_skills> catalog rendered into
+// the cached system prompt without touching skill loading or invocation.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { buildSystemPrompt } from "../core/system-prompt.js";
+import type { Skill } from "../core/skills.js";
+
+function makeSkill(name: string, description = `description for ${name}`): Skill {
+	return {
+		name,
+		description,
+		filePath: `/tmp/${name}/SKILL.md`,
+		baseDir: `/tmp/${name}`,
+		source: "project",
+		disableModelInvocation: false,
+	};
+}
+
+function extractAvailableSkills(prompt: string): string {
+	const start = prompt.indexOf("<available_skills>");
+	const end = prompt.indexOf("</available_skills>");
+	if (start === -1 || end === -1) return "";
+	return prompt.slice(start, end + "</available_skills>".length);
+}
+
+// ─── Default branch (no customPrompt) ──────────────────────────────────────
+
+test("buildSystemPrompt: skillFilter omits filtered-out skills from <available_skills>", () => {
+	const skills = [makeSkill("alpha"), makeSkill("beta"), makeSkill("gamma")];
+	const prompt = buildSystemPrompt({
+		skills,
+		selectedTools: ["read", "Skill"],
+		skillFilter: skill => skill.name !== "beta",
+	});
+
+	const section = extractAvailableSkills(prompt);
+	assert.ok(section.length > 0, "catalog section should render");
+	assert.match(section, /<name>alpha<\/name>/);
+	assert.match(section, /<name>gamma<\/name>/);
+	assert.doesNotMatch(section, /<name>beta<\/name>/);
+});
+
+test("buildSystemPrompt: skillFilter omitted preserves pre-filter behavior (all skills render)", () => {
+	const skills = [makeSkill("alpha"), makeSkill("beta")];
+	const prompt = buildSystemPrompt({
+		skills,
+		selectedTools: ["read", "Skill"],
+	});
+
+	const section = extractAvailableSkills(prompt);
+	assert.match(section, /<name>alpha<\/name>/);
+	assert.match(section, /<name>beta<\/name>/);
+});
+
+test("buildSystemPrompt: skillFilter that rejects every skill suppresses the <available_skills> block", () => {
+	const skills = [makeSkill("alpha"), makeSkill("beta")];
+	const prompt = buildSystemPrompt({
+		skills,
+		selectedTools: ["read", "Skill"],
+		skillFilter: () => false,
+	});
+
+	// With zero visible skills, formatSkillsForPrompt returns an empty string,
+	// so the opening tag should not appear anywhere.
+	assert.ok(!prompt.includes("<available_skills>"));
+});
+
+// ─── Custom-prompt branch ──────────────────────────────────────────────────
+
+test("buildSystemPrompt (customPrompt): skillFilter applies to the catalog appended onto a custom prompt", () => {
+	const skills = [makeSkill("alpha"), makeSkill("beta"), makeSkill("gamma")];
+	const prompt = buildSystemPrompt({
+		customPrompt: "CUSTOM BASE",
+		skills,
+		selectedTools: ["read", "Skill"],
+		skillFilter: skill => skill.name === "alpha",
+	});
+
+	const section = extractAvailableSkills(prompt);
+	assert.match(section, /<name>alpha<\/name>/);
+	assert.doesNotMatch(section, /<name>beta<\/name>/);
+	assert.doesNotMatch(section, /<name>gamma<\/name>/);
+});
+
+// ─── Interaction with disableModelInvocation ──────────────────────────────
+
+test("buildSystemPrompt: skillFilter composes with disableModelInvocation (both must pass)", () => {
+	// A skill already hidden from the catalog by disableModelInvocation must
+	// remain hidden even if skillFilter would otherwise admit it. The filter
+	// narrows, it does not override the existing invisibility contract.
+	const skills: Skill[] = [
+		{ ...makeSkill("visible"), disableModelInvocation: false },
+		{ ...makeSkill("hidden"), disableModelInvocation: true },
+	];
+	const prompt = buildSystemPrompt({
+		skills,
+		selectedTools: ["read", "Skill"],
+		skillFilter: () => true,
+	});
+
+	const section = extractAvailableSkills(prompt);
+	assert.match(section, /<name>visible<\/name>/);
+	assert.doesNotMatch(section, /<name>hidden<\/name>/);
+});
+
+// ─── Pass-through of non-filtered fields ──────────────────────────────────
+
+test("buildSystemPrompt: skillFilter does not affect context files or cwd rendering", () => {
+	const skills = [makeSkill("alpha")];
+	const prompt = buildSystemPrompt({
+		skills,
+		cwd: "/tmp/example",
+		contextFiles: [{ path: "CLAUDE.md", content: "project instructions" }],
+		selectedTools: ["read", "Skill"],
+		skillFilter: () => false,
+	});
+
+	assert.ok(prompt.includes("/tmp/example"), "cwd should still render");
+	assert.ok(prompt.includes("project instructions"), "context files should still render");
+	assert.ok(!prompt.includes("<available_skills>"), "no skill catalog when filter rejects all");
+});
+
+// ─── Exception safety ─────────────────────────────────────────────────────
+
+test("buildSystemPrompt: skillFilter that throws falls back to unfiltered list and does not propagate", (t) => {
+	// A buggy consumer predicate must not bubble out of buildSystemPrompt.
+	// If it did, _rebuildSystemPrompt could unwind mid-setTools() and leave
+	// the session with updated tools but a stale system prompt.
+	const skills = [makeSkill("alpha"), makeSkill("beta")];
+
+	// Suppress the console.warn the fallback emits so test output stays clean.
+	const originalWarn = console.warn;
+	const warnings: string[] = [];
+	console.warn = (...args: unknown[]) => { warnings.push(args.join(" ")); };
+	t.after(() => { console.warn = originalWarn; });
+
+	let prompt = "";
+	assert.doesNotThrow(() => {
+		prompt = buildSystemPrompt({
+			skills,
+			selectedTools: ["read", "Skill"],
+			skillFilter: () => { throw new Error("consumer bug"); },
+		});
+	});
+
+	const section = extractAvailableSkills(prompt);
+	assert.match(section, /<name>alpha<\/name>/, "alpha should render (fallback to unfiltered)");
+	assert.match(section, /<name>beta<\/name>/, "beta should render (fallback to unfiltered)");
+	assert.ok(
+		warnings.some(w => w.includes("skillFilter threw") && w.includes("consumer bug")),
+		"fallback should emit an identifying warning",
+	);
+});