gsd-pi 2.77.0-dev.1d17f366c → 2.77.0-dev.2daa994b6

package/packages/pi-coding-agent/src/core/resource-loader-cache-reset.test.ts

@@ -1,42 +1,107 @@
-// GSD-2 — Regression test for #3616: reload() must reset jiti extension loader cache
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+// Regression test for #3616: DefaultResourceLoader.reload() must invalidate
+// the jiti module cache before loading extensions, so that edits to
+// extension source on disk are picked up on the next reload (not served
+// stale from memory).
+//
+// Verified end-to-end behaviourally: we write a .ts extension that
+// registers a tool whose NAME is a module-scope constant, load it,
+// rewrite the source with a new constant value, reload(), and assert
+// the observable tool name reflects the NEW source. Without jiti cache
+// invalidation, the second reload would re-register the stale name.
 
-import test, { describe } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
 
-const source = readFileSync(
-	join(process.cwd(), "packages/pi-coding-agent/src/core/resource-loader.ts"),
-	"utf-8",
-);
+import { DefaultResourceLoader } from "./resource-loader.js";
+import { SettingsManager } from "./settings-manager.js";
+import { resetExtensionLoaderCache } from "./extensions/loader.js";
 
-describe("#3616 — reload() must invalidate jiti module cache", () => {
-	test("resource-loader imports resetExtensionLoaderCache from loader.js", () => {
-		assert.ok(
-			source.includes("resetExtensionLoaderCache"),
-			"resource-loader.ts should import resetExtensionLoaderCache",
-		);
-		assert.ok(
-			source.includes('from "./extensions/loader.js"'),
-			"resetExtensionLoaderCache should be imported from extensions/loader.js",
-		);
+let testDir: string;
+
+function writeExtensionWithToolName(extPath: string, toolName: string): void {
+	// Extension factory signature expected by the loader. Uses `any` so the
+	// test stays decoupled from the ExtensionAPI type shape.
+	writeFileSync(
+		extPath,
+		[
+			`const TOOL_NAME = "${toolName}";`,
+			`export default function activate(api: any) {`,
+			`  api.registerTool({`,
+			`    name: TOOL_NAME,`,
+			`    label: TOOL_NAME,`,
+			`    description: "test tool — source-generated name",`,
+			`    parameters: { type: "object", properties: {}, additionalProperties: false },`,
+			`    execute: async () => ({ content: [], details: undefined }),`,
+			`  });`,
+			`}`,
+			"",
+		].join("\n"),
+	);
+}
+
+describe("#3616 — DefaultResourceLoader.reload() invalidates extension module cache", () => {
+	beforeEach(() => {
+		testDir = mkdtempSync(join(tmpdir(), "resource-loader-cache-reset-"));
+		// Ensure a clean jiti singleton — prior tests in this process may
+		// have populated it with unrelated entries.
+		resetExtensionLoaderCache();
+	});
+
+	afterEach(() => {
+		resetExtensionLoaderCache();
+		rmSync(testDir, { recursive: true, force: true });
 	});
 
-	test("reload() calls resetExtensionLoaderCache before loadExtensions", () => {
-		const reloadStart = source.indexOf("async reload(): Promise<void>");
-		assert.ok(reloadStart >= 0, "should find reload() method");
-		const reloadBody = source.slice(reloadStart, reloadStart + 4000);
+	it("reload() picks up source edits after the extension has been loaded once", async () => {
+		const agentDir = join(testDir, "agent-home");
+		const extPath = join(testDir, "reload-probe.ts");
 
-		const resetIdx = reloadBody.indexOf("resetExtensionLoaderCache()");
-		assert.ok(resetIdx >= 0, "reload() should call resetExtensionLoaderCache()");
+		// v1 — initial content
+		writeExtensionWithToolName(extPath, "probe_v1");
 
-		const loadIdx = reloadBody.indexOf("loadExtensions(");
-		assert.ok(loadIdx >= 0, "reload() should call loadExtensions");
+		const loader = new DefaultResourceLoader({
+			cwd: testDir,
+			agentDir,
+			settingsManager: SettingsManager.inMemory(),
+			noExtensions: true,
+			noPromptTemplates: true,
+			noThemes: true,
+			additionalExtensionPaths: [extPath],
+		});
 
+		await loader.reload();
+
+		const toolsV1 = [...loader.getExtensions().extensions.flatMap((e) => [...e.tools.keys()])];
+		assert.ok(
+			toolsV1.includes("probe_v1"),
+			`first reload should register probe_v1; got=${JSON.stringify(toolsV1)}`,
+		);
+
+		// v2 — overwrite the source on disk with a different tool name.
+		writeExtensionWithToolName(extPath, "probe_v2");
+		// Bump mtime explicitly so file-stat–based cache strategies (jiti's
+		// moduleCache consults Node's require.cache, which some runtimes
+		// tiebreak on mtime) always see "newer than last seen". On Windows
+		// NTFS + node the default fs mtime resolution can silently collapse
+		// two writes in the same tick to an identical mtime — that fooled
+		// the Windows CI run on #3616.
+		const futureTime = new Date(Date.now() + 5000);
+		utimesSync(extPath, futureTime, futureTime);
+
+		await loader.reload();
+
+		const toolsV2 = [...loader.getExtensions().extensions.flatMap((e) => [...e.tools.keys()])];
+		assert.ok(
+			toolsV2.includes("probe_v2"),
+			`second reload must observe the edited source (probe_v2) — if reload() ` +
+				`fails to reset the jiti cache, the stale module returns probe_v1. got=${JSON.stringify(toolsV2)}`,
+		);
 		assert.ok(
-			resetIdx < loadIdx,
-			"resetExtensionLoaderCache() must be called BEFORE loadExtensions to ensure fresh modules",
+			!toolsV2.includes("probe_v1"),
+			`second reload must NOT still expose the stale probe_v1 name; got=${JSON.stringify(toolsV2)}`,
 		);
 	});
 });

package/packages/pi-coding-agent/src/core/retry-handler.test.ts

@@ -281,7 +281,11 @@ describe("RetryHandler — long-context entitlement 429 (#2803)", () => {
 			assert.equal(result, true, "retry should be initiated");
 
 			handler.abortRetry();
-			await new Promise((resolve) => setTimeout(resolve, 10));
+			// Yield the microtask queue so any synchronous continuation
+			// scheduled by abortRetry() settles before we assert. This is
+			// deterministic — no magic-sleep dependency (#4798 / #4784).
+			await Promise.resolve();
+			await Promise.resolve();
 
 			assert.equal(continueFn.mock.calls.length, 0, "cancelled retry must not continue after explicit abort");
 			const endEvents = emittedEvents.filter((e) => e.type === "auto_retry_end");

package/packages/pi-coding-agent/src/core/retry-handler.ts

@@ -18,6 +18,7 @@ import type { ModelRegistry } from "./model-registry.js";
 import type { SettingsManager } from "./settings-manager.js";
 import { sleep } from "../utils/sleep.js";
 import type { AgentSessionEvent } from "./agent-session.js";
+import { RETRYABLE_ERROR_RE } from "./retryable-error-regex.js";
 
 /** Dependencies injected from AgentSession into RetryHandler */
 export interface RetryHandlerDeps {
@@ -111,14 +112,7 @@ export class RetryHandler {
 		const contextWindow = this._deps.getModel()?.contextWindow ?? 0;
 		if (isContextOverflow(message, contextWindow)) return false;
 
-		const err = message.errorMessage;
-		// "temporarily backed off" is intentionally excluded: it is an internally-
-		// generated error from getApiKey() when credentials are in a backoff window.
-		// Re-entering the retry handler for that message creates a cascade of empty
-		// error entries in the session file, breaking resume (#3429).
-		return /overloaded|rate.?limit|too many requests|402|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|requires more credits|can only afford|insufficient credits|not enough credits|extra usage is required|(?:out of|no) extra usage|third.party.*draw from extra|third.party.*not.*available/i.test(
-			err,
-		);
+		return RETRYABLE_ERROR_RE.test(message.errorMessage);
 	}
 
 	/**

package/packages/pi-coding-agent/src/core/retryable-error-regex.ts

@@ -0,0 +1,18 @@
+/**
+ * Regex matching retryable provider errors — overloaded, rate limits, transient
+ * server/connection failures, credential-backoff, quota/credit issues.
+ *
+ * Kept in its own zero-import module so tests can consume the live pattern
+ * without pulling in the full RetryHandler dependency graph (Agent /
+ * FallbackResolver / ModelRegistry / @gsd/pi-ai …). The test in
+ * `src/resources/extensions/gsd/tests/provider-errors.test.ts` previously
+ * redefined this regex inline, which meant runtime and test could drift
+ * silently on every edit (see #4837).
+ *
+ * "temporarily backed off" is intentionally excluded: it is an internally-
+ * generated error from getApiKey() when credentials are in a backoff window.
+ * Re-entering the retry handler for that message creates a cascade of empty
+ * error entries in the session file, breaking resume (#3429).
+ */
+export const RETRYABLE_ERROR_RE =
+	/overloaded|rate.?limit|too many requests|402|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|requires more credits|can only afford|insufficient credits|not enough credits|extra usage is required|(?:out of|no) extra usage|third.party.*draw from extra|third.party.*not.*available/i;

package/packages/pi-coding-agent/src/core/system-prompt.ts

@@ -35,6 +35,26 @@ export interface BuildSystemPromptOptions {
 	contextFiles?: Array<{ path: string; content: string }>;
 	/** Pre-loaded skills. */
 	skills?: Skill[];
+	/**
+	 * Optional predicate applied to the `skills` list before rendering the
+	 * <available_skills> catalog. Returning `false` omits a skill from the
+	 * prompt (the skill remains loaded and invocable by name — only the
+	 * catalog listing is suppressed).
+	 *
+	 * Intended for consumers that can narrow the relevant skill surface
+	 * (e.g. per-unit-type manifests) to reduce cached system-prompt bloat.
+	 * When omitted, all non-`disableModelInvocation` skills render — i.e.
+	 * behavior is unchanged from before this option existed.
+	 *
+	 * Contract: the predicate must be **pure and synchronous**. It may be
+	 * invoked on every system-prompt rebuild (tool-set changes and
+	 * runtime resource-loader extensions both trigger one), so any state
+	 * the closure captures should be stable across the rebuild window.
+	 * If the predicate throws, `buildSystemPrompt` logs a warning and
+	 * falls back to the unfiltered skill list — callers never see the
+	 * exception and the session stays consistent.
+	 */
+	skillFilter?: (skill: Skill) => boolean;
 }
 
 /** Build the system prompt with tools, guidelines, and context */
@@ -48,6 +68,7 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 		cwd,
 		contextFiles: providedContextFiles,
 		skills: providedSkills,
+		skillFilter,
 	} = options;
 	const resolvedCwd = toPosixPath(cwd ?? process.cwd());
 
@@ -66,7 +87,20 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 	const appendSection = appendSystemPrompt ? `\n\n${appendSystemPrompt}` : "";
 
 	const contextFiles = providedContextFiles ?? [];
-	const skills = providedSkills ?? [];
+	const skillsBase = providedSkills ?? [];
+	let skills = skillsBase;
+	if (skillFilter) {
+		try {
+			skills = skillsBase.filter(skillFilter);
+		} catch (error) {
+			// A consumer's predicate threw. Fall back to the unfiltered list so
+			// the session stays consistent — callers (e.g. AgentSession.setTools)
+			// must not be left with updated tools but a stale system prompt.
+			const message = error instanceof Error ? error.message : String(error);
+			console.warn(`buildSystemPrompt: skillFilter threw; falling back to unfiltered skills. Error: ${message}`);
+			skills = skillsBase;
+		}
+	}
 
 	if (customPrompt) {
 		let prompt = customPrompt;

package/packages/pi-coding-agent/src/index.ts

@@ -188,6 +188,7 @@ export type { PackageCommand, PackageCommandOptions, PackageCommandRunnerOptions
 export { getPackageCommandUsage, parsePackageCommand, runPackageCommand } from "./core/package-commands.js";
 export type { ResourceCollision, ResourceDiagnostic, ResourceLoader } from "./core/resource-loader.js";
 export { DefaultResourceLoader } from "./core/resource-loader.js";
+export { RETRYABLE_ERROR_RE } from "./core/retryable-error-regex.js";
 // SDK for programmatic usage
 export {
 	type CreateAgentSessionOptions,

package/packages/pi-coding-agent/src/modes/interactive/components/__tests__/tool-execution.test.ts

@@ -14,12 +14,13 @@ function renderTool(
 		isError: boolean;
 		details?: Record<string, unknown>;
 	},
+	toolDefinition?: { label?: string },
 ): string {
 	const component = new ToolExecutionComponent(
 		toolName,
 		args,
 		{},
-		undefined,
+		toolDefinition as any,
 		{ requestRender() {} } as any,
 	);
 	component.setExpanded(true);
@@ -35,12 +36,13 @@ function renderToolCollapsed(
 		isError: boolean;
 		details?: Record<string, unknown>;
 	},
+	toolDefinition?: { label?: string },
 ): string {
 	const component = new ToolExecutionComponent(
 		toolName,
 		args,
 		{},
-		undefined,
+		toolDefinition as any,
 		{ requestRender() {} } as any,
 	);
 	if (result) component.updateResult(result);
@@ -110,13 +112,57 @@ describe("ToolExecutionComponent", () => {
 			{ count: 3, enabled: true, label: "hello" },
 		);
 
-		assert.match(rendered, /some_unknown_tool/);
+		assert.match(rendered, /Some Unknown Tool/);
 		assert.match(rendered, /count=3/);
 		assert.match(rendered, /enabled=true/);
 		assert.match(rendered, /label="hello"/);
 		assert.doesNotMatch(rendered, /^\{$/m);
 	});
 
+	test("frame header prefers toolDefinition.label over raw tool name", () => {
+		const rendered = renderToolCollapsed(
+			"gsd_slice_complete",
+			{ sliceId: "S03" },
+			undefined,
+			{ label: "Complete Slice" },
+		);
+
+		assert.match(rendered, /Tool Complete Slice/);
+		assert.doesNotMatch(rendered, /gsd_slice_complete/);
+	});
+
+	test("frame header strips gsd_ prefix and title-cases when no label is registered", () => {
+		const rendered = renderToolCollapsed("gsd_requirement_update", { id: "R005" });
+
+		assert.match(rendered, /Tool Requirement Update/);
+		assert.doesNotMatch(rendered, /gsd_requirement_update/);
+	});
+
+	test("formatCompactArgs truncates long string values inline instead of dumping JSON", () => {
+		const longPath = "/Users/alice/.gsd/projects/4dce7b775013/worktrees/slice-S03-some-long-path-that-exceeds-limit";
+		const rendered = renderToolCollapsed("gsd_slice_complete", {
+			sliceId: "S03",
+			milestoneId: "M001",
+			worktree: longPath,
+		});
+
+		assert.match(rendered, /sliceId="S03"/);
+		assert.match(rendered, /milestoneId="M001"/);
+		assert.match(rendered, /worktree=".*…"/);
+		assert.doesNotMatch(rendered, /"sliceId":\s*"S03"/);
+	});
+
+	test("formatCompactArgs shows full string values when expanded", () => {
+		const longPath = "/Users/alice/.gsd/projects/4dce7b775013/worktrees/slice-S03-some-long-path-that-exceeds-limit";
+		const rendered = renderTool("gsd_slice_complete", {
+			sliceId: "S03",
+			worktree: longPath,
+		});
+
+		assert.match(rendered, new RegExp(longPath.replace(/\//g, "\\/")));
+		assert.doesNotMatch(rendered, /…/);
+	});
+
 	test("generic fallback truncates long output when collapsed", () => {
 		const longOutput = Array.from({ length: 25 }, (_, i) => `line ${i + 1}`).join("\n");
 		const rendered = renderToolCollapsed(

package/packages/pi-coding-agent/src/modes/interactive/components/dynamic-border.test.ts

@@ -37,26 +37,32 @@ describe("DynamicBorder spinner", () => {
 		border.stopSpinner();
 	});
 
-	it("triggers standalone render when no external render occurred recently", async () => {
-		const border = new DynamicBorder((s) => s);
-		const tui = makeTUI();
-
-		// Set lastExternalRender to a time well in the past
-		const anyBorder = border as any;
-		anyBorder.lastExternalRender = 0;
-
-		border.startSpinner(tui as any, (s) => s);
-		const initialCount = tui.renderCount;
-
-		// Wait for one spinner tick (200ms interval + buffer)
-		await new Promise((r) => setTimeout(r, 250));
-
-		assert.ok(
-			tui.renderCount > initialCount,
-			"spinner should trigger requestRender when no recent external render",
-		);
-
-		border.stopSpinner();
+	it("triggers standalone render when no external render occurred recently", () => {
+		mock.timers.enable({ apis: ["setInterval"], now: 0 });
+		try {
+			const border = new DynamicBorder((s) => s);
+			const tui = makeTUI();
+
+			// Set lastExternalRender to a time well in the past
+			const anyBorder = border as any;
+			anyBorder.lastExternalRender = 0;
+
+			border.startSpinner(tui as any, (s) => s);
+			const initialCount = tui.renderCount;
+
+			// Advance exactly one spinner interval (200ms). With mocked timers
+			// this is deterministic — no flake under CI load.
+			mock.timers.tick(200);
+
+			assert.ok(
+				tui.renderCount > initialCount,
+				"spinner should trigger requestRender after one 200ms interval when no recent external render",
+			);
+
+			border.stopSpinner();
+		} finally {
+			mock.timers.reset();
+		}
 	});
 
 	it("updates lastExternalRender on each render() call", () => {

package/packages/pi-coding-agent/src/modes/interactive/components/tool-execution.ts

@@ -66,6 +66,21 @@ function parseMcpToolName(name: string): { server: string; tool: string } | null
 	return { server: rest.slice(0, delim), tool: rest.slice(delim + 2) };
 }
 
+/**
+ * Prettify a raw tool name for display. Prefers the registered `label`
+ * ("Complete Slice") when available; otherwise strips a leading `gsd_`
+ * prefix and converts snake_case to Title Case.
+ */
+function prettifyToolName(name: string, label?: string): string {
+	if (label && label.trim().length > 0) return label;
+	const stripped = name.replace(/^gsd_/, "");
+	if (stripped.length === 0) return name;
+	return stripped
+		.split("_")
+		.map((word) => (word.length === 0 ? word : word[0].toUpperCase() + word.slice(1)))
+		.join(" ");
+}
+
 type ToolFrameTone = "pending" | "success" | "error";
 
 function trimOuterBlankLines(lines: string[]): string[] {
@@ -131,15 +146,19 @@ function formatCompactArgs(args: unknown, expanded: boolean): string {
 
 	const allPrimitive = entries.every(([, value]) => {
 		const t = typeof value;
-		if (t === "number" || t === "boolean") return true;
-		if (t === "string") return (value as string).length <= COMPACT_ARG_VALUE_LIMIT;
-		return value == null;
+		return t === "number" || t === "boolean" || t === "string" || value == null;
 	});
 
 	if (allPrimitive) {
 		return entries
 			.map(([key, value]) => {
-				if (typeof value === "string") return `${key}=${JSON.stringify(value)}`;
+				if (typeof value === "string") {
+					const truncated =
+						!expanded && value.length > COMPACT_ARG_VALUE_LIMIT
+							? `${value.slice(0, COMPACT_ARG_VALUE_LIMIT - 1)}…`
+							: value;
+					return `${key}=${JSON.stringify(truncated)}`;
+				}
 				if (value == null) return `${key}=null`;
 				return `${key}=${String(value)}`;
 			})
@@ -526,7 +545,7 @@ export class ToolExecutionComponent extends Container {
 		const parsed = parseMcpToolName(this.toolName);
 		const frameLabel = parsed
 			? `Tool ${parsed.server}·${parsed.tool}`
-			: `Tool ${this.normalizedToolName || this.toolName || "unknown"}`;
+			: `Tool ${prettifyToolName(this.toolName, this.toolDefinition?.label) || "unknown"}`;
 		const framed = renderToolFrame(lines, frameWidth, {
 			label: frameLabel,
 			status: frameStatus,
@@ -570,12 +589,30 @@ export class ToolExecutionComponent extends Container {
 					}
 				} catch {
 					// Fall back to default on error
-					this.contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.toolName)), 0, 0));
+					this.contentBox.addChild(
+						new Text(
+							theme.fg(
+								"toolTitle",
+								theme.bold(prettifyToolName(this.toolName, this.toolDefinition?.label)),
+							),
+							0,
+							0,
+						),
+					);
 					customRendererHasContent = true;
 				}
 			} else {
-				// No custom renderCall, show tool name
-				this.contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.toolName)), 0, 0));
+				// No custom renderCall, show prettified tool name
+				this.contentBox.addChild(
+					new Text(
+						theme.fg(
+							"toolTitle",
+							theme.bold(prettifyToolName(this.toolName, this.toolDefinition?.label)),
+						),
+						0,
+						0,
+					),
+				);
 				customRendererHasContent = true;
 			}
 
@@ -1126,7 +1163,9 @@ export class ToolExecutionComponent extends Container {
 			// cleanly. GSD-registered MCP tools have already had their prefix
 			// stripped upstream in partial-builder.ts and won't reach this branch.
 			const parsed = parseMcpToolName(this.toolName);
-			const displayName = parsed ? parsed.tool : this.toolName;
+			const displayName = parsed
+				? parsed.tool
+				: prettifyToolName(this.toolName, this.toolDefinition?.label);
 			const serverPrefix = parsed ? theme.fg("muted", `${parsed.server}\u00b7`) : "";
 			text = serverPrefix + theme.fg("toolTitle", theme.bold(displayName));
 

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",
+	);
+});