one-code-extension 0.1.3 → 0.3.0

package/extensions/lib/claude-context.ts

@@ -14,14 +14,27 @@
  * down to the cwd. (pi's resource-loader prefers AGENTS.md over CLAUDE.md per
  * dir and omits CLAUDE.local.md / MEMORY.md, so it can't produce these bytes.)
  *
+ * Two One Code additions layer on top of that Claude Code base, both no-ops when
+ * unused so the block stays byte-exact for anyone who doesn't reach for them:
+ *   - `@path` imports inside any context file are expanded in place, matching
+ *     Claude Code (recursive, depth-capped, cycle-safe, code-span aware) — so a
+ *     CLAUDE.md that just says `@AGENTS.md` reuses an existing AGENTS.md.
+ *   - `ONECODE.md` / `onecode.md` / `One Code.md` files (global `~/.onecode` +
+ *     each project directory) carry One Code-specific instructions that Claude
+ *     Code never reads. They ride their OWN `# oneCodeMd` block (see
+ *     `buildOneCodeBlock` / `discoverOneCodeFiles`), emitted after the `# claudeMd`
+ *     block so they take precedence over CLAUDE.md — keeping `# claudeMd` itself
+ *     byte-exact with Claude Code.
+ *
  * What is NOT yet replicated: enterprise-policy files and nested subtree
  * CLAUDE.md loaded on-demand when a file under them is read (a follow-up needing
  * file-tracker integration; absent from every turn-1 capture we have).
  */
 
-import { existsSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
 import { tryReadFile } from "./plugins.ts";
+import { expandTilde } from "./paths.ts";
 
 /** One CLAUDE.md-family file as it appears in the block. `content` is raw (untrimmed). */
 export interface ContextFile {
@@ -34,6 +47,15 @@ export const GLOBAL_DESCRIPTOR = "user's private global instructions for all pro
 export const PROJECT_DESCRIPTOR = "project instructions, checked into the codebase";
 export const LOCAL_DESCRIPTOR = "user's private project instructions, not checked in";
 export const MEMORY_DESCRIPTOR = "user's auto-memory, persists across conversations";
+export const ONECODE_DESCRIPTOR = "One Code-specific instructions, not read by Claude Code";
+export const ONECODE_GLOBAL_DESCRIPTOR =
+	"One Code-specific global instructions for all projects, not read by Claude Code";
+
+/** One Code instruction filenames, in preference order (first present per dir wins). */
+const ONECODE_NAMES = ["ONECODE.md", "onecode.md", "One Code.md"] as const;
+
+/** Max `@import` hops, matching Claude Code. Depth 0 is the importing file itself. */
+const MAX_IMPORT_DEPTH = 5;
 
 const PREAMBLE =
 	"As you answer the user's questions, you can use the following context:\n" +
@@ -60,48 +82,317 @@ function readFileIfPresent(path: string): string | null {
  * first, then project files from the farthest ancestor down to the cwd. Within a
  * directory, `CLAUDE.md` then `CLAUDE.local.md`. `homeClaudeDir` is `~/.claude`.
  */
-export function discoverContextFiles(opts: {
-	cwd: string;
-	homeClaudeDir: string;
-}): ContextFile[] {
-	const files: ContextFile[] = [];
-	const seen = new Set<string>();
+function isPresentFile(path: string): boolean {
+	try {
+		return existsSync(path) && statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The One Code instruction file in `dir`, or null. Prefers an exact candidate
+ * casing, then any case-insensitive match, and returns the file's real on-disk
+ * name so `Contents of {path}` stays accurate on case-insensitive filesystems
+ * (macOS), where `onecode.md` on disk would otherwise be reported as `ONECODE.md`.
+ *
+ * Fast path first: cheap `stat` probes of the candidate names, so the common case
+ * (no One Code file in this directory — true of every ancestor up to the root)
+ * costs a few stats and never lists the directory. Only when a probe hits do we
+ * read the directory once to recover the real casing.
+ */
+function firstOneCodeFile(dir: string): string | null {
+	if (!ONECODE_NAMES.some((n) => isPresentFile(join(dir, n)))) return null;
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return null;
+	}
+	const pick = ONECODE_NAMES.find((n) => entries.includes(n)) ?? entries.find((e) => e.toLowerCase() === "onecode.md");
+	if (pick && isPresentFile(join(dir, pick))) return join(dir, pick);
+	return null;
+}
 
-	const globalPath = join(opts.homeClaudeDir, "CLAUDE.md");
-	const globalContent = readFileIfPresent(globalPath);
-	if (globalContent !== null) {
-		files.push({ path: globalPath, content: globalContent, descriptor: GLOBAL_DESCRIPTOR });
-		seen.add(globalPath);
+/** Resolve an `@import` reference: `~`/`~/` → home, absolute as-is, else relative to `baseDir`. */
+function resolveImportPath(ref: string, baseDir: string, home: string): string {
+	const p = expandTilde(ref, home);
+	return isAbsolute(p) ? p : join(baseDir, p);
+}
+
+/**
+ * Read a `@import` target, tolerating trailing sentence punctuation (`@a/b.md.`).
+ * Returns the resolved path, its raw content, and any stripped trailing text to
+ * re-append after the inlined content. `null` when nothing readable resolves.
+ */
+function readImportTarget(
+	ref: string,
+	baseDir: string,
+	home: string,
+	read: (path: string) => string | null,
+	stack: Set<string>,
+): { resolved: string; content: string; trailing: string } | null {
+	let candidate = ref;
+	for (;;) {
+		const resolved = resolveImportPath(candidate, baseDir, home);
+		if (!stack.has(resolved)) {
+			const content = read(resolved);
+			if (content !== null) return { resolved, content, trailing: ref.slice(candidate.length) };
+		}
+		// Not a readable file (and not a cycle already on the stack): peel one trailing
+		// punctuation char and retry, so `@docs/x.md.` still resolves `docs/x.md`.
+		if (candidate.length <= 1 || !/[.,;:!?)\]]$/.test(candidate)) return null;
+		candidate = candidate.slice(0, -1);
+	}
+}
+
+/**
+ * Claude Code's `@path` imports: replace each `@path` reference with the
+ * referenced file's (recursively expanded) contents. `@` inside inline-code spans
+ * or fenced code blocks is left alone; a reference that does not resolve to a
+ * readable file is left as literal text; cycles and hops past MAX_IMPORT_DEPTH
+ * stop recursion. `read` defaults to the module's own file reader (injectable for
+ * tests). A file with no importable `@` tokens is returned unchanged.
+ */
+export function expandImports(
+	content: string,
+	baseDir: string,
+	opts: { home: string; read?: (path: string) => string | null },
+): string {
+	return expandImportsInner(content, baseDir, opts.home, opts.read ?? readFileIfPresent, new Set<string>(), 0);
+}
+
+/**
+ * The absolute paths every `@path` import in `content` resolves to, transitively
+ * (same traversal, resolution, cycle/depth rules as `expandImports`). Used to
+ * tell whether a file — e.g. an `AGENTS.md` — is actually pulled into context,
+ * rather than merely present on disk.
+ */
+export function collectImportedPaths(
+	content: string,
+	baseDir: string,
+	opts: { home: string; read?: (path: string) => string | null },
+): Set<string> {
+	const found = new Set<string>();
+	expandImportsInner(content, baseDir, opts.home, opts.read ?? readFileIfPresent, new Set<string>(), 0, (p) =>
+		found.add(p),
+	);
+	return found;
+}
+
+function expandImportsInner(
+	content: string,
+	baseDir: string,
+	home: string,
+	read: (path: string) => string | null,
+	stack: Set<string>,
+	depth: number,
+	onResolve?: (path: string) => void,
+): string {
+	if (depth >= MAX_IMPORT_DEPTH) return content;
+	if (!content.includes("@")) return content;
+
+	const out: string[] = [];
+	let inFence = false;
+	let fenceMarker = "";
+	for (const line of content.split("\n")) {
+		const fence = line.match(/^\s*(`{3,}|~{3,})/);
+		if (fence) {
+			const marker = fence[1][0];
+			if (!inFence) {
+				inFence = true;
+				fenceMarker = marker;
+			} else if (marker === fenceMarker) {
+				inFence = false;
+				fenceMarker = "";
+			}
+			out.push(line);
+			continue;
+		}
+		out.push(inFence ? line : expandImportLine(line, baseDir, home, read, stack, depth, onResolve));
 	}
+	return out.join("\n");
+}
+
+function expandImportLine(
+	line: string,
+	baseDir: string,
+	home: string,
+	read: (path: string) => string | null,
+	stack: Set<string>,
+	depth: number,
+	onResolve?: (path: string) => void,
+): string {
+	if (!line.includes("@")) return line;
+
+	// Shield inline-code spans so `@path` inside backticks is never expanded. NUL
+	// delimiters can't occur in source text, so restoration never mis-fires on a
+	// real number that happens to be surrounded by spaces.
+	const spans: string[] = [];
+	const shielded = line.replace(/(`+)[\s\S]*?\1/g, (m) => {
+		spans.push(m);
+		return `\u0000${spans.length - 1}\u0000`;
+	});
 
-	// Walk cwd → root collecting directories, then emit farthest-ancestor first.
+	const replaced = shielded.replace(/(^|\s)@(\S+)/g, (whole, lead: string, ref: string) => {
+		const target = readImportTarget(ref, baseDir, home, read, stack);
+		if (!target) return whole; // unresolved or cycle: leave the literal text
+		onResolve?.(target.resolved);
+		const next = new Set(stack);
+		next.add(target.resolved);
+		const expanded = expandImportsInner(target.content, dirname(target.resolved), home, read, next, depth + 1, onResolve);
+		return `${lead}${expanded}${target.trailing}`;
+	});
+
+	return replaced.replace(/\u0000(\d+)\u0000/g, (_m, i: string) => spans[Number(i)]);
+}
+
+/** A discovered CLAUDE.md-family path and its descriptor, without file content. */
+export interface ContextFilePath {
+	path: string;
+	descriptor: string;
+}
+
+/** The cwd and each ancestor up to the filesystem root, ordered farthest-first. */
+export function ancestorDirs(cwd: string): string[] {
 	const dirs: string[] = [];
-	let dir = opts.cwd;
+	let dir = cwd;
 	while (true) {
 		dirs.unshift(dir);
 		const parent = dirname(dir);
 		if (parent === dir) break;
 		dir = parent;
 	}
+	return dirs;
+}
 
-	for (const d of dirs) {
-		for (const [name, descriptor] of [
-			["CLAUDE.md", PROJECT_DESCRIPTOR],
-			["CLAUDE.local.md", LOCAL_DESCRIPTOR],
-		] as const) {
-			const p = join(d, name);
-			if (seen.has(p)) continue;
-			const content = readFileIfPresent(p);
-			if (content !== null) {
-				files.push({ path: p, content, descriptor });
-				seen.add(p);
-			}
+/**
+ * The ordered CLAUDE.md-family paths that exist, WITHOUT reading their contents:
+ * global `~/.claude/CLAUDE.md` first, then project `CLAUDE.md`/`CLAUDE.local.md`
+ * from the farthest ancestor down to cwd (`CLAUDE.md` before `CLAUDE.local.md`
+ * within a directory). `discoverContextFiles` reads content on top of this;
+ * callers that only need paths/descriptors (e.g. `/memory`'s picker) use it
+ * directly to avoid loading files they will discard.
+ *
+ * When `homeOneCodeDir` is given, One Code's own `ONECODE.md` files join the
+ * list: the global one from `~/.onecode` right after the global CLAUDE.md, and
+ * each directory's after its CLAUDE.md/CLAUDE.local.md. The `/memory` picker passes
+ * it (so ONECODE.md is an editable target); the model-facing `# claudeMd` block
+ * does NOT — there ONECODE.md rides its own `# oneCodeMd` block via
+ * `discoverOneCodeFiles` instead, so `# claudeMd` stays byte-exact with CC.
+ *
+ * When `agentsFallback` is set, a directory with no `CLAUDE.md` falls back to its
+ * `AGENTS.md` (CLAUDE.md > AGENTS.md — the first-match Codex/opencode do, but
+ * CLAUDE-preferred for our CC-compat audience). A directory that has a CLAUDE.md
+ * ignores its AGENTS.md, so `# claudeMd` stays byte-exact with CC whenever
+ * CLAUDE.md is present.
+ */
+export function discoverContextFilePaths(opts: {
+	cwd: string;
+	homeClaudeDir: string;
+	homeOneCodeDir?: string;
+	agentsFallback?: boolean;
+}): ContextFilePath[] {
+	const paths: ContextFilePath[] = [];
+	const seen = new Set<string>();
+	const includeOneCode = opts.homeOneCodeDir !== undefined;
+
+	/** Adds the path if present; returns whether it was added. */
+	const push = (path: string, descriptor: string): boolean => {
+		if (seen.has(path) || !isPresentFile(path)) return false;
+		paths.push({ path, descriptor });
+		seen.add(path);
+		return true;
+	};
+
+	push(join(opts.homeClaudeDir, "CLAUDE.md"), GLOBAL_DESCRIPTOR);
+	if (includeOneCode && opts.homeOneCodeDir) {
+		const globalOneCode = firstOneCodeFile(opts.homeOneCodeDir);
+		if (globalOneCode) push(globalOneCode, ONECODE_GLOBAL_DESCRIPTOR);
+	}
+
+	for (const d of ancestorDirs(opts.cwd)) {
+		const hasClaude = push(join(d, "CLAUDE.md"), PROJECT_DESCRIPTOR);
+		// AGENTS.md stands in for a missing CLAUDE.md in this directory.
+		if (!hasClaude && opts.agentsFallback) push(join(d, "AGENTS.md"), AGENTS_DESCRIPTOR);
+		push(join(d, "CLAUDE.local.md"), LOCAL_DESCRIPTOR);
+		if (includeOneCode) {
+			const oneCode = firstOneCodeFile(d);
+			if (oneCode) push(oneCode, ONECODE_DESCRIPTOR);
 		}
 	}
 
+	return paths;
+}
+
+export function discoverContextFiles(opts: {
+	cwd: string;
+	homeClaudeDir: string;
+	homeOneCodeDir?: string;
+	agentsFallback?: boolean;
+	/** Home directory for resolving `~` in `@path` imports. */
+	home: string;
+}): ContextFile[] {
+	const files: ContextFile[] = [];
+	for (const { path, descriptor } of discoverContextFilePaths(opts)) {
+		// Re-check the read: a file present at enumeration but unreadable now is
+		// omitted, exactly as before (the block must never carry empty entries).
+		const content = readFileIfPresent(path);
+		if (content === null) continue;
+		files.push({ path, content: expandImports(content, dirname(path), { home: opts.home }), descriptor });
+	}
+	return files;
+}
+
+/**
+ * The ONECODE.md files that exist, ordered global-first then farthest ancestor
+ * down to cwd (nearer wins). These ride in their own `# oneCodeMd` block, not the
+ * `# claudeMd` block, so the latter stays byte-exact with Claude Code.
+ */
+function discoverOneCodeFilePaths(opts: { cwd: string; homeOneCodeDir: string }): ContextFilePath[] {
+	const paths: ContextFilePath[] = [];
+	const seen = new Set<string>();
+	const push = (path: string | null, descriptor: string) => {
+		if (!path || seen.has(path)) return;
+		paths.push({ path, descriptor });
+		seen.add(path);
+	};
+	push(firstOneCodeFile(opts.homeOneCodeDir), ONECODE_GLOBAL_DESCRIPTOR);
+	for (const d of ancestorDirs(opts.cwd)) push(firstOneCodeFile(d), ONECODE_DESCRIPTOR);
+	return paths;
+}
+
+/** ONECODE.md files with `@import`s expanded, for the `# oneCodeMd` block. */
+export function discoverOneCodeFiles(opts: { cwd: string; homeOneCodeDir: string; home: string }): ContextFile[] {
+	const files: ContextFile[] = [];
+	for (const { path, descriptor } of discoverOneCodeFilePaths(opts)) {
+		const content = readFileIfPresent(path);
+		if (content === null) continue;
+		files.push({ path, content: expandImports(content, dirname(path), { home: opts.home }), descriptor });
+	}
 	return files;
 }
 
+const ONECODE_PREAMBLE =
+	"# oneCodeMd\n" +
+	"The following are One Code-specific instructions, read only by One Code and not by other tools. " +
+	"IMPORTANT: they take precedence over the CLAUDE.md instructions above and over any default behavior — " +
+	"where they conflict with CLAUDE.md, follow these. Follow them exactly as written.";
+
+/**
+ * Assemble the `# oneCodeMd` block's inner text (wrapper added by lib/reminders.ts):
+ * the precedence preamble, then one `Contents of {path} ({descriptor}):\n\n{content}`
+ * section per file (same raw-content join as the claudeMd block). Returns null when
+ * there are no ONECODE.md files, so nothing extra rides when the feature is unused.
+ */
+export function buildOneCodeBlock(files: ContextFile[]): string | null {
+	if (files.length === 0) return null;
+	const sections = files.map((s) => `Contents of ${s.path} (${s.descriptor}):\n\n${s.content}`).join("\n");
+	return `${ONECODE_PREAMBLE}\n\n${sections}`;
+}
+
+export const AGENTS_DESCRIPTOR = "cross-tool agent instructions, AGENTS.md standard";
+
 /**
  * Assemble the block's inner text (the `<system-reminder>` wrapper is added by
  * lib/reminders.ts). Byte-exact rule reverse-engineered from opus-4-8.json:

package/extensions/lib/claude-settings.ts

@@ -0,0 +1,64 @@
+/**
+ * Read-only access to Claude Code's settings files (pure fs, no pi imports).
+ *
+ * Sources, lowest to highest precedence — the same ladder the permissions
+ * extension merges:
+ *   ~/.claude/settings.json           (user)
+ *   <cwd>/.claude/settings.json       (project, checked in)
+ *   <cwd>/.claude/settings.local.json (project, personal)
+ *
+ * One Code NEVER writes these files. Plugin enable/disable initiated from One
+ * Code goes to the One Code plugin root (lib/plugin-overrides.ts), never here.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { claudeUserDir } from "./paths.ts";
+
+export interface ClaudeSettingsFile {
+	enabledPlugins?: Record<string, unknown>;
+	[key: string]: unknown;
+}
+
+/**
+ * Claude Code's *user* settings file. The one canonical statement of that path,
+ * so the loaders that must recognise "the borrowed `.claude` user file" (to skip
+ * One Code's own keys found there) all compare against the same value.
+ */
+export function claudeUserSettingsPath(home: string): string {
+	return join(claudeUserDir(home), "settings.json");
+}
+
+export function settingsPaths(cwd: string, home: string): { user: string; project: string; local: string } {
+	return {
+		user: claudeUserSettingsPath(home),
+		project: join(cwd, ".claude", "settings.json"),
+		local: join(cwd, ".claude", "settings.local.json"),
+	};
+}
+
+export function readSettingsFile(path: string): ClaudeSettingsFile | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")) as ClaudeSettingsFile;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Claude Code's plugin enabled-state map (`{"name@marketplace": boolean}`),
+ * merged across the three settings files — later files win per key.
+ */
+export function readEnabledPlugins(cwd: string, home: string): Record<string, boolean> {
+	const paths = settingsPaths(cwd, home);
+	const merged: Record<string, boolean> = {};
+	for (const path of [paths.user, paths.project, paths.local]) {
+		const enabled = readSettingsFile(path)?.enabledPlugins;
+		if (!enabled || typeof enabled !== "object") continue;
+		for (const [key, value] of Object.entries(enabled)) {
+			if (typeof value === "boolean") merged[key] = value;
+		}
+	}
+	return merged;
+}

package/extensions/lib/consent-preview.ts

@@ -0,0 +1,30 @@
+/**
+ * Bounding for text shown in a consent modal (pure).
+ *
+ * A consent dialog lists what an untrusted repo wants to run — hook commands,
+ * MCP server commands. The list must not hide where an attack lives (so a single
+ * item is shown in full up to a generous per-item cap, never an 80-char slice),
+ * but it also must not render megabytes into a modal (hundreds of items, or one
+ * pathologically long one). This bounds the total: full items until a budget,
+ * each item capped, then a pointer to the real file (which is the source of
+ * truth the user should read before approving anything this large).
+ */
+
+const PER_ITEM_CAP = 2000;
+const TOTAL_CAP = 4000;
+
+export function boundConsentItems(items: string[], moreHint: string): string {
+	const shown: string[] = [];
+	let used = 0;
+	for (const item of items) {
+		const capped = item.length > PER_ITEM_CAP ? `${item.slice(0, PER_ITEM_CAP)}… [truncated, ${item.length} chars]` : item;
+		// Always show the first item (so an empty modal never happens); stop once
+		// the budget is spent.
+		if (shown.length > 0 && used + capped.length + 1 > TOTAL_CAP) break;
+		shown.push(capped);
+		used += capped.length + 1;
+	}
+	const hidden = items.length - shown.length;
+	const more = hidden > 0 ? `\n… and ${hidden} more not shown — ${moreHint}` : "";
+	return shown.join("\n") + more;
+}

package/extensions/lib/deferred.ts

@@ -10,6 +10,9 @@
  * `{ name, keywords? }` while extensions are loading (before session_start).
  */
 
+import { parseClaudeVersion } from "./model-tier.ts";
+import { normalizeToolName } from "../permissions/matcher.ts";
+
 export const DEFER_CHANNEL = "one-code:defer-tool";
 
 export interface DeferRequest {
@@ -46,31 +49,155 @@ export class DeferredRegistry {
 	}
 }
 
-export const deferredRegistry = new DeferredRegistry();
+// The one registry instance is constructed by its owner (tool-search/index.ts):
+// a shared export here would be a distinct object in every other extension's
+// jiti module graph, and a tool deferred through that copy would steer nothing.
 
 /**
  * The every-turn reminder telling the model which tools exist but are not
- * loaded. One line per tool (first description line only), like Claude Code's
- * deferred-tools listing.
+ * loaded — Claude Code's shape (cc-haiku.json, message 1, block 1): one fixed
+ * sentence, then bare names one per line. No descriptions: the model searches
+ * by keyword through `tool_search` (which does see descriptions), and a name-
+ * only list is ~7x smaller — the description form grew by several KB per MCP
+ * server and was the single largest block after `# claudeMd`. The wording is
+ * CC's with our tool name and our dispatcher's actual error text; it stays
+ * byte-identical after a load (as CC's does) so the cached prefix holds — a
+ * loaded tool is simply callable, and the sentence says as much.
+ */
+export function deferredReminderText(tools: Array<Pick<SearchableTool, "name"> & Partial<SearchableTool>>): string {
+	return [
+		'The following deferred tools are available via tool_search. Their schemas are NOT loaded — calling one directly fails with "Tool <name> not found" until you load it. Use tool_search with query "select:<name>[,<name>...]" to load tool schemas before calling them (once loaded, a tool stays callable for the rest of the session):',
+		...tools.map((t) => t.name),
+	].join("\n");
+}
+
+/**
+ * The one-shot that announces deferred tools which registered AFTER the first
+ * request went out (a slow MCP connect, a reconnect, a plugin install). The
+ * standing listing on message 1 is frozen once cached (tool-search/announce.ts);
+ * this rides the tail instead, so the cached prefix holds.
  */
-export function deferredReminderText(tools: Array<Pick<SearchableTool, "name" | "description">>): string {
+export function deferredAddendumText(added: readonly string[]): string {
 	return [
-		"The following tools are available but their schemas are NOT loaded, so they cannot be called yet:",
-		...tools.map((t) => `- ${t.name}: ${t.description.split("\n")[0]}`),
-		"",
-		"Load one with tool_search before using it — `select:<name>[,<name>]` for exact names, or keywords to search. Once a schema is loaded it stays callable for the rest of the session.",
+		"Additional deferred tools became available via tool_search since this conversation started (they registered after the first request). Same rules: load with tool_search \"select:<name>\" before calling.",
+		...added,
 	].join("\n");
 }
 
+/**
+ * Whether Anthropic accepts client-side `tool_reference` blocks for this model —
+ * pi-ai's `defaultSupportsToolReferences` rule, with the model's own compat flag
+ * winning: first-party Anthropic, not Haiku, Claude 4.5 or newer.
+ */
+export function supportsToolReferences(
+	model: { provider?: string; id?: string; compat?: { supportsToolReferences?: boolean } } | undefined,
+): boolean {
+	if (!model) return false;
+	if (typeof model.compat?.supportsToolReferences === "boolean") return model.compat.supportsToolReferences;
+	if (model.provider !== "anthropic" || !model.id || model.id.includes("haiku")) return false;
+	const version = parseClaudeVersion(model.id);
+	return version !== undefined && (version.major > 4 || (version.major === 4 && version.minor >= 5));
+}
+
+/** The slice of pi's ToolInfo the deferred definitions need. */
+export interface DeferrableToolInfo {
+	name: string;
+	description?: string;
+	parameters?: { properties?: unknown; required?: unknown };
+}
+
+/**
+ * An Anthropic request with every deferred tool that pi left out appended as a
+ * `defer_loading: true` definition, sorted by name (pi's own entries stay first
+ * and untouched). Anthropic keeps deferred definitions out of the cached prefix,
+ * but ADDING one to `tools` mid-session still re-caches the message history —
+ * measured 2026-09-04 on Sonnet 5: the request after a `tool_search` load read
+ * only tools + system (8.7k of 25k tokens); with the full deferred set present
+ * from request 1 it read all 25k. Unloaded deferred definitions cost no input
+ * tokens, so sending them always is free and keeps `tools` byte-stable.
+ *
+ * Returns undefined (leave the payload alone) when there is nothing to add, the
+ * request carries no tools, or the tool names on the wire are not the registry's
+ * (pi's OAuth "stealth" mode renames them to Claude Code casing, and a name that
+ * cannot be matched must not be duplicated). Schemas follow pi's own
+ * `convertTools` shape. Never mutates its input.
+ */
+export function withDeferredToolDefinitions(
+	payload: Record<string, unknown>,
+	tools: readonly DeferrableToolInfo[],
+	isDeferred: (name: string) => boolean,
+): Record<string, unknown> | undefined {
+	const existing = payload.tools;
+	if (!Array.isArray(existing) || existing.length === 0) return undefined;
+	const registry = new Set(tools.map((t) => t.name));
+	const present = new Set<string>();
+	for (const tool of existing) {
+		const name = (tool as { name?: unknown } | null)?.name;
+		if (typeof name !== "string" || !registry.has(name)) return undefined;
+		present.add(name);
+	}
+	const extra = tools
+		.filter((t) => isDeferred(t.name) && !present.has(t.name))
+		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+		.map((t) => ({
+			name: t.name,
+			description: t.description ?? "",
+			input_schema: {
+				type: "object",
+				properties: t.parameters?.properties ?? {},
+				required: t.parameters?.required ?? [],
+			},
+			defer_loading: true,
+		}));
+	if (extra.length === 0) return undefined;
+	return { ...payload, tools: [...existing, ...extra] };
+}
+
+/**
+ * The bare error pi's core dispatcher returns when the model calls a tool whose
+ * schema isn't in the active set — including every deferred tool before
+ * `tool_search` loads it (pi-agent-core `prepareToolCall`). The message is
+ * `Tool <name> not found`; this recovers `<name>` so a deferred miss can be
+ * steered back to `tool_search`. Returns undefined for any other error text.
+ */
+export function toolNotFoundName(text: string): string | undefined {
+	return /^Tool (\S+) not found$/.exec(text.trim())?.[1];
+}
+
+/** Flatten a tool result's content blocks to plain text (results are untyped over the bus). */
+export function resultText(result: unknown): string {
+	const content = (result as { content?: unknown })?.content;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((block) => (block && typeof block === "object" && "text" in block ? String((block as { text: unknown }).text) : ""))
+		.join("");
+}
+
+/**
+ * The one-shot correction that rides in right after a deferred tool's
+ * "not found" failure, pointing the model at `tool_search` instead of leaving it
+ * to recover from the bare error on its own.
+ */
+export function deferredMissReminderText(name: string): string {
+	return [
+		`\`${name}\` is a deferred tool — its schema is not loaded, so that call failed with "Tool ${name} not found".`,
+		`Load it first with tool_search (\`select:${name}\`), then reissue the call. It stays callable for the rest of the session once loaded.`,
+	].join(" ");
+}
+
 export interface SearchMatch {
 	name: string;
 	score: number;
 }
 
 /**
- * The exact names a `select:` query asks for (lowercased), or undefined when the
- * query is not a select: query. Lets tool_search report which requested names
- * matched nothing instead of silently dropping them.
+ * The exact names a `select:` query asks for (lowercased and mapped through the
+ * Claude Code alias table), or undefined when the query is not a select: query.
+ * A CC-trained model writes `select:WebFetch,NotebookEdit`; without the alias
+ * pass those are "not found — check spelling" even though the tools exist under
+ * our names (TOOL-FIDELITY-REVIEW-2026-09-07 M1). Lets tool_search report which
+ * requested names matched nothing instead of silently dropping them.
  */
 export function selectedNames(query: string): string[] | undefined {
 	const trimmed = query.trim();
@@ -78,8 +205,12 @@ export function selectedNames(query: string): string[] | undefined {
 	return trimmed
 		.slice("select:".length)
 		.split(",")
-		.map((n) => n.trim().toLowerCase())
-		.filter(Boolean);
+		.map((n) => n.trim())
+		.filter(Boolean)
+		// normalizeToolName lowercases ordinary names but PRESERVES case for
+		// `mcp__…` names; the trailing toLowerCase keeps select: case-insensitive
+		// for those too. Don't drop it as "redundant".
+		.map((n) => normalizeToolName(n).toLowerCase());
 }
 
 /**