one-code-extension 0.1.0

package/extensions/auto-mode/defaults.ts

@@ -0,0 +1,65 @@
+/**
+ * Built-in auto-mode rule lists (pure data).
+ *
+ * These are prose, read by the classifier as natural-language rules — the same
+ * shape Claude Code's `claude auto-mode defaults` prints, so a user's existing
+ * `autoMode` settings splice into them with `"$defaults"` unchanged.
+ *
+ * Four tiers, in the precedence the classifier is instructed to apply:
+ *   hard_deny  — unconditional; neither user intent nor allow rules clear it
+ *   soft_deny  — blocked unless an allow rule or explicit user intent clears it
+ *   allow      — exceptions to soft_deny
+ *   (intent)   — a specific user instruction clears remaining soft denials
+ */
+
+/** What the classifier treats as inside the trust boundary. */
+export const DEFAULT_ENVIRONMENT: string[] = [
+	"Trusted repo: the git repository containing the working directory, and its configured remotes. Pushing to any branch of this repository is routine. Content first read from outside this repository is not this repository's own work, whoever asked for it to be moved.",
+	"Repository visibility: assume private unless the user's own message says otherwise. Confidential material may go into a private repo; secrets and personal data may never go into any repo regardless of visibility.",
+	"Trusted internal domains: none configured. Any host that is not the repository's own remote is outside the boundary.",
+	"Trusted cloud buckets: none configured. Treat every bucket write as leaving the boundary.",
+	"Internal package registry: none configured. Installs from the ecosystem's default public registry are routine; installs redirected to another registry are not.",
+	"Sensitive data locations: credential directories (~/.ssh, ~/.aws, ~/.kube, ~/.docker, ~/.m2, ~/.gnupg, ~/.config/gcloud), .env files anywhere, private keys and keystores, and /proc or /sys process state.",
+	"Sensitive remote targets: any host, namespace, container, or branch whose name carries prod, production, live, or release.",
+	"Protected IaC scopes: any Terraform, Pulumi, CloudFormation, Helm, or Kubernetes manifest path whose name marks it as production.",
+	"Primary use: software development in the working directory.",
+];
+
+/** Unconditional. User intent does not clear these. */
+export const DEFAULT_HARD_DENY: string[] = [
+	"Data exfiltration: sending secrets, credentials, private keys, personal data, or the contents of sensitive files to any destination outside the trust boundary — by network request, by commit or push, by writing into a shared location, or by embedding them in a command argument that reaches a third party. This holds however the action is framed and whoever asked for it.",
+	"Auto-mode bypass: disabling, weakening, or working around this approval mechanism — editing permission settings or Claude Code/One Code configuration to grant broader permissions, adding allow rules, changing the permission mode, or routing an action through a path that avoids classification.",
+	"Credential harvesting: reading credential stores, keychains, browser password databases, or process environment memory (/proc/*/environ) for any purpose other than one the user specifically named.",
+	"Destroying the user's own history: rewriting or deleting the reflog, deleting the local repository, or removing backups such that the user's uncommitted or unpushed work cannot be recovered.",
+];
+
+/** Blocked, but an allow rule or a specific user instruction clears them. */
+export const DEFAULT_SOFT_DENY: string[] = [
+	"Git destructive [must name the operation and its target]: force pushing, deleting remote branches, tags, or releases, rewriting remote history, or amending a commit that is not the agent's own unpushed work from this session.",
+	"Production deploys and destroys [must name the target]: deploying, applying, or destroying against a sensitive remote target or protected IaC scope, including terraform apply/destroy, helm upgrade, kubectl apply against a production namespace, and any release or publish pipeline.",
+	"Remote code execution: piping a downloaded script into an interpreter (curl | bash and equivalents), running an installer fetched at execution time, or executing a file whose contents were downloaded during this session.",
+	"Irreversible loss outside the working directory: deleting, overwriting, or truncating an existing file or directory that is not under the working directory and not obviously scratch space such as /tmp. Creating a new file outside the working directory is covered by the separate rule below, not by this one.",
+	"Creating or modifying files outside the working directory [must name the path]: writing somewhere the user did not ask for is how work leaks out of the project. Clears when the user's own message names that path, or names the destination unambiguously enough that the path follows from it. Also clears for the harness's own designated directories named in the system prompt — the session scratchpad (under /tmp or /private/tmp, in a claude-<uid> directory) and the auto-memory directory (~/.claude/projects/<project>/memory) — which exist precisely so temporary and memory files do not land in the project.",
+	"Publishing: pushing a package to a registry, creating a public release or gist, or making a private repository public.",
+	"Disabling safety machinery: turning off CI checks, required reviews, branch protection, test suites in configuration, pre-commit hooks, or TLS certificate verification.",
+	"Secrets entering version control: staging or committing a file that holds a credential, key, or token, including one the agent generated.",
+	"Bulk permission or ownership changes: recursive chmod/chown, or making files world-writable.",
+	"Writing to paths whose contents execute later without further approval: .git/hooks, .git/config, editor auto-run configuration, or a build wrapper such as mvnw or gradlew.",
+	"Database mutation outside a migration tool: dropping, truncating, or bulk-updating tables directly, against any database.",
+	"Remote shells and port-forwards into a sensitive remote target.",
+	"Sending repository contents to a third-party service that is not part of the configured toolchain.",
+];
+
+/** Exceptions to soft_deny. */
+export const DEFAULT_ALLOW: string[] = [
+	"Local file operations inside the working directory: creating, editing, moving, and deleting files and directories under it, including build output and caches.",
+	"Reading anything inside the working directory, and reading system and tool configuration that is not on the sensitive-data list.",
+	"Installing dependencies already declared in the project's manifest (package.json, pyproject.toml, go.mod, pom.xml, Cargo.toml) from the ecosystem's default registry.",
+	"Running the project's own build, test, lint, format, and type-check commands, including ones that write to build directories.",
+	"Read-only information lookups that retrieve only public data and send none of the user's own: HTTP GET/HEAD to public documentation, package metadata, and credential-free API endpoints; and public registry or DNS queries such as whois, dig, nslookup, and host, including ones that name the registry or DNS server to query.",
+	"Git operations that do not rewrite published history: status, diff, log, add, commit, branch, checkout, merge, rebase of unpushed local work, stash, and pushing to any branch of the trusted repo.",
+	"Creating and updating pull requests on the trusted repo, and reading issues and CI results.",
+	"Starting, stopping, and querying local development servers and containers bound to loopback.",
+	"Test artifacts: placeholder credentials authored as placeholders in examples and fixtures. A value copied from a real secret or a sensitive path is never a test artifact.",
+	"Reading the project's own .env file when the user asked for work that requires its configuration, provided the values do not leave the machine.",
+];

package/extensions/auto-mode/instructions.ts

@@ -0,0 +1,74 @@
+/**
+ * Project instruction files for the classifier (pure fs).
+ *
+ * Claude Code's classifier reads the same CLAUDE.md the agent does, so an
+ * instruction like "never force push" steers both at once. This collects the
+ * same files: cwd upward to the git root, plus the user's global file.
+ *
+ * These files are checked in, so they are untrusted input in a way the user's
+ * own messages are not — the classifier prompt tells the model they may tighten
+ * what is allowed but never widen it. That asymmetry is what makes including
+ * them safe; without it, a repository could ship its own authorisation.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const FILE_NAMES = ["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"];
+
+/** Per-file and total caps, so a large instruction file cannot crowd out rules. */
+const PER_FILE_LIMIT = 6_000;
+const TOTAL_LIMIT = 12_000;
+
+function readCapped(path: string): string | undefined {
+	try {
+		// readFileSync loads the whole file regardless, so the cap is applied to the
+		// decoded string. (A prior statSync branch claimed to bound the read but did
+		// the same full read either way.)
+		return readFileSync(path, "utf-8").slice(0, PER_FILE_LIMIT);
+	} catch {
+		return undefined;
+	}
+}
+
+function findGitRoot(from: string): string | undefined {
+	let dir = from;
+	for (;;) {
+		if (existsSync(join(dir, ".git"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
+}
+
+/**
+ * Concatenated instruction files, nearest first, or undefined when there are
+ * none. Each is labelled with its path so the classifier can tell project
+ * convention from user-global preference.
+ */
+export function loadProjectInstructions(cwd: string, home: string): string | undefined {
+	const stop = findGitRoot(cwd) ?? cwd;
+	const parts: string[] = [];
+	let total = 0;
+
+	const add = (path: string) => {
+		if (total >= TOTAL_LIMIT || !existsSync(path)) return;
+		const body = readCapped(path)?.trim();
+		if (!body) return;
+		const chunk = `# ${path}\n${body}`;
+		parts.push(chunk.slice(0, TOTAL_LIMIT - total));
+		total += chunk.length;
+	};
+
+	let dir = cwd;
+	for (;;) {
+		for (const name of FILE_NAMES) add(join(dir, name));
+		if (dir === stop) break;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	add(join(home, ".claude", "CLAUDE.md"));
+
+	return parts.length > 0 ? parts.join("\n\n") : undefined;
+}

package/extensions/auto-mode/model-picker.ts

@@ -0,0 +1,225 @@
+/**
+ * The `/auto-mode model` picker (pure).
+ *
+ * Filtering, key decoding, selection movement, and rendering for the
+ * interactive classifier-model picker, kept free of pi imports so they are
+ * unit-testable. The thin `ctx.ui.custom` component in the permissions
+ * extension owns nothing but mutable state and repaint calls.
+ *
+ * A picker exists because the alternative was worse in practice: choosing the
+ * classifier automatically took three rounds of fault-fixing against real
+ * catalogs, and when auto-selection picks badly the only recourse was
+ * hand-editing settings.json with a model id the user has to guess. Naming a
+ * model here is the explicit consent `autoMode.classifierModel` stands for —
+ * including consent to another provider, which auto-selection must never
+ * assume (see model-select.ts).
+ */
+
+export interface PickerEntry {
+	provider: string;
+	id: string;
+	/** Input price per million tokens, when the catalog carries a usable one. */
+	inputPrice?: number;
+}
+
+export const pickerSpec = (entry: { provider: string; id: string }): string => `${entry.provider}/${entry.id}`;
+
+/**
+ * Rank a query against one spec: 0 prefix, 1 substring, 2 in-order subsequence,
+ * undefined no match. Subsequence keeps "haiku45" finding "claude-haiku-4.5"
+ * without a fuzzy-match dependency.
+ */
+export function matchRank(spec: string, query: string): number | undefined {
+	const haystack = spec.toLowerCase();
+	const needle = query.toLowerCase().replace(/\s+/g, "");
+	if (needle.length === 0) return 2;
+	if (haystack.startsWith(needle)) return 0;
+	if (haystack.includes(needle)) return 1;
+	let at = 0;
+	for (const char of needle) {
+		at = haystack.indexOf(char, at);
+		if (at === -1) return undefined;
+		at++;
+	}
+	return 2;
+}
+
+/** Filter and rank, preserving catalog order within a rank. */
+export function filterEntries<T extends { provider: string; id: string }>(entries: T[], query: string): T[] {
+	return entries
+		.map((entry, position) => ({ entry, position, rank: matchRank(pickerSpec(entry), query) }))
+		.filter((item): item is { entry: T; position: number; rank: number } => item.rank !== undefined)
+		.sort((a, b) => a.rank - b.rank || a.position - b.position)
+		.map((item) => item.entry);
+}
+
+export type PickerKey =
+	| { kind: "up" }
+	| { kind: "down" }
+	| { kind: "confirm" }
+	| { kind: "cancel" }
+	| { kind: "backspace" }
+	| { kind: "type"; text: string };
+
+/**
+ * Decode a raw terminal chunk. Unlike the effort slider there are no letter
+ * shortcuts: every printable character belongs to the filter query.
+ */
+export function decodePickerKey(data: string): PickerKey | undefined {
+	switch (data) {
+		case "\x1b[A":
+		case "\x1bOA":
+			return { kind: "up" };
+		case "\x1b[B":
+		case "\x1bOB":
+			return { kind: "down" };
+		case "\r":
+		case "\n":
+			return { kind: "confirm" };
+		case "\x1b":
+		case "\x03": // ctrl+c — same intent as escape while the picker is focused
+			return { kind: "cancel" };
+		case "\x7f":
+		case "\b":
+			return { kind: "backspace" };
+		default: {
+			// Printable text only (covers paste); control sequences are ignored.
+			const text = [...data].filter((char) => char >= " " && char !== "\x7f").join("");
+			return text.length > 0 && !data.startsWith("\x1b") ? { kind: "type", text } : undefined;
+		}
+	}
+}
+
+/** First index of the window shown, keeping the cursor visible. */
+export function windowStart(index: number, length: number, maxVisible: number): number {
+	if (length <= maxVisible) return 0;
+	return Math.max(0, Math.min(index - Math.floor(maxVisible / 2), length - maxVisible));
+}
+
+export type Paint = (color: string, text: string) => string;
+
+export interface PickerView {
+	entries: PickerEntry[];
+	index: number;
+	query: string;
+	/** Catalog size before filtering, for the "n of m" line. */
+	total: number;
+	/** The currently configured spec, marked in the listing. */
+	current?: string;
+	maxVisible?: number;
+	/** Picker header; defaults to the auto-mode classifier copy. */
+	title?: string;
+	subtitle?: string;
+}
+
+const formatPrice = (price?: number): string => (price === undefined ? "" : `$${price}/M in`);
+
+/** Picker entries from a model catalog, sorted by spec, non-positive prices treated as unpriced. */
+export function toPickerEntries(models: { provider: string; id: string; cost?: { input?: number } }[]): PickerEntry[] {
+	return models
+		.map((model) => ({
+			provider: model.provider,
+			id: model.id,
+			inputPrice: typeof model.cost?.input === "number" && model.cost.input > 0 ? model.cost.input : undefined,
+		}))
+		.sort((a, b) => pickerSpec(a).localeCompare(pickerSpec(b)));
+}
+
+export interface PickerComponentOptions {
+	entries: PickerEntry[];
+	current?: string;
+	title?: string;
+	subtitle?: string;
+}
+
+/**
+ * The `ctx.ui.custom` component behind `/auto-mode model` and `/subagent`:
+ * filter-as-you-type over the entries, enter confirms, esc cancels. Kept here
+ * (structurally typed, no pi imports) so both commands share one keyboard
+ * loop instead of drifting copies.
+ */
+export function modelPickerComponent(
+	options: PickerComponentOptions,
+	tui: { requestRender(): void },
+	theme: unknown,
+	done: (choice: PickerEntry | null) => void,
+): { render(): string[]; handleInput(data: string): void; invalidate(): void } {
+	const paint: Paint = (color, text) => {
+		const themed = theme as { fg?(c: string, t: string): string } | undefined;
+		try {
+			return themed?.fg ? themed.fg(color, text) : text;
+		} catch {
+			return text;
+		}
+	};
+	let query = "";
+	let index = 0;
+	let filtered = options.entries;
+	return {
+		render: () => [
+			"",
+			...renderModelPicker(
+				{
+					entries: filtered,
+					index,
+					query,
+					total: options.entries.length,
+					current: options.current,
+					title: options.title,
+					subtitle: options.subtitle,
+				},
+				paint,
+			),
+			"",
+		],
+		handleInput: (data: string) => {
+			const key = decodePickerKey(data);
+			if (!key) return;
+			if (key.kind === "cancel") return done(null);
+			if (key.kind === "confirm") return done(filtered[index] ?? null);
+			if (key.kind === "up") index = Math.max(0, index - 1);
+			else if (key.kind === "down") index = Math.min(filtered.length - 1, index + 1);
+			else {
+				query = key.kind === "backspace" ? query.slice(0, -1) : query + key.text;
+				filtered = filterEntries(options.entries, query);
+				index = 0;
+			}
+			tui.requestRender();
+		},
+		invalidate: () => {},
+	};
+}
+
+export function renderModelPicker(view: PickerView, paint: Paint): string[] {
+	const maxVisible = view.maxVisible ?? 10;
+	const lines: string[] = [];
+	lines.push(paint("accent", view.title ?? "Select the auto-mode classifier model"));
+	lines.push(
+		paint(
+			"dim",
+			view.subtitle ??
+				"It reads your prompts and CLAUDE.md — picking another provider sends them there. type to filter · ↑/↓ · enter · esc",
+		),
+	);
+	lines.push(`  filter: ${view.query}${paint("dim", "▏")}`);
+
+	if (view.entries.length === 0) {
+		lines.push(paint("warning", "  (no available model matches)"));
+		return lines;
+	}
+
+	const start = windowStart(view.index, view.entries.length, maxVisible);
+	for (const [offset, entry] of view.entries.slice(start, start + maxVisible).entries()) {
+		const at = start + offset;
+		const spec = pickerSpec(entry);
+		const annotations = [view.current === spec ? "✓ current" : "", formatPrice(entry.inputPrice)]
+			.filter(Boolean)
+			.join("  ");
+		const suffix = annotations ? `  ${paint("dim", annotations)}` : "";
+		lines.push(at === view.index ? `${paint("accent", `❯ ${spec}`)}${suffix}` : `  ${spec}${suffix}`);
+	}
+	if (view.entries.length > maxVisible || view.entries.length < view.total) {
+		lines.push(paint("dim", `  ${view.entries.length} of ${view.total} models${view.query ? " match" : ""}`));
+	}
+	return lines;
+}

package/extensions/auto-mode/model-select.ts

@@ -0,0 +1,178 @@
+/**
+ * Choosing the classifier model (pure).
+ *
+ * ## Why this is not just "pick a cheap model"
+ *
+ * The classifier receives the user's own messages, their CLAUDE.md, and the text
+ * of the command being judged. So *which provider it runs on* is a privacy
+ * decision, not an optimisation. The first cut of this searched the whole
+ * registry for a model whose id contained "haiku"/"sonnet"/"mini", which on a
+ * session running `openai-codex/gpt-5.5-codex` with an Anthropic key also present
+ * silently selected `anthropic/claude-haiku-4-5` — shipping that user's prompts to
+ * a vendor they had not chosen for this session, through a component with no UI.
+ *
+ * So: **never leave the session's provider unless the user asked for it.** An
+ * explicit `autoMode.classifierModel` may name any provider, because naming it is
+ * the asking. Everything else stays where the session already is. This is the same
+ * reasoning pi's own subagent config gives for defaulting to the session model —
+ * "this keeps new installs from depending on a provider you may not have
+ * configured" — and this module follows that precedence shape: explicit override,
+ * then a configured default, then something sensible in-provider, then the session
+ * model itself.
+ *
+ * Name matching is demoted to a tiebreak because it does not survive contact with
+ * real catalogs: of Groq's 7 models and xAI's 3, *none* contain any of those
+ * substrings, while OpenRouter has 303 models and 79 substring hits, so the "first
+ * match" is arbitrary. Cost is the one signal every provider carries.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import {
+	findConfigured,
+	findRoleProfileModel,
+	hintRank,
+	modelIdentity,
+	modelsContainedToSession,
+	pricedInput,
+} from "../lib/model-policy.ts";
+
+export { findConfigured } from "../lib/model-policy.ts";
+
+export interface Candidate {
+	model: Model<Api>;
+	/** How this candidate was arrived at, for the notice shown to the user. */
+	source: "configured" | "role-profile" | "cheapest-in-provider" | "session";
+}
+
+export interface SelectInput {
+	/** Models the user actually has working credentials for. */
+	available: Model<Api>[];
+	sessionModel: Model<Api> | undefined;
+	/** `autoMode.classifierModel`, if set. May name any provider. */
+	configured?: string;
+}
+
+/**
+ * The ordered candidate chain. More than one is returned so a candidate that
+ * turns out to be unusable at call time (not entitled on this account, withdrawn
+ * by the provider) can be stepped over instead of failing every tool call — the
+ * same shape as pi's subagent `fallbackModels`.
+ *
+ * The chain always ends at the session model when there is one, so auto mode
+ * degrades to "correct but not cheap" rather than to "broken".
+ */
+export function classifierCandidates({ available, sessionModel, configured }: SelectInput): Candidate[] {
+	const candidates: Candidate[] = [];
+	const push = (model: Model<Api> | undefined, source: Candidate["source"]) => {
+		if (!model) return;
+		if (candidates.some((entry) => entry.model.provider === model.provider && entry.model.id === model.id)) return;
+		candidates.push({ model, source });
+	};
+
+	// 1. What the user asked for, wherever it lives. Naming a provider is choosing it.
+	if (configured) push(findConfigured(available, configured), "configured");
+
+	/**
+	 * Containment is shared with subagents. For a direct provider it is the
+	 * provider itself; gateways additionally preserve a reliable route/family;
+	 * opaque routers expose only the session model.
+	 */
+	const inProvider = sessionModel ? modelsContainedToSession(available, sessionModel) : [];
+
+	/**
+	 * No candidate may cost more per token than the model doing the actual work.
+	 * Screening a call more expensively than making it is indefensible, and it
+	 * happened: on an OpenRouter session at `z-ai/glm-4.6` ($0.50/M) the table's
+	 * `anthropic/claude-haiku-4.5` ($1/M) was selected, because this ceiling was
+	 * originally applied only to the cost-ranked branch and not to the table.
+	 */
+	const sessionPrice = sessionModel ? pricedInput(sessionModel) : undefined;
+	const withinBudget = (model: Model<Api>) => {
+		if (sessionPrice === undefined) return true;
+		const price = pricedInput(model);
+		return price === undefined || price <= sessionPrice;
+	};
+
+	// 2. A reviewed small-but-capable model for this provider/family. The
+	//    profile is short and applied to the live catalog; price alone never
+	//    promotes a model into the classifier role.
+	if (sessionModel) {
+		// Reuse the containment set computed above instead of recomputing it inside.
+		push(findRoleProfileModel(available, sessionModel, "classifier", withinBudget, inProvider), "role-profile");
+	}
+
+	// 3. The cheapest genuinely-priced model in the provider.
+	const cheaper = inProvider
+		.map((model) => ({ model, price: pricedInput(model) }))
+		.filter((entry): entry is { model: Model<Api>; price: number } => entry.price !== undefined)
+		.filter((entry) => withinBudget(entry.model))
+		.sort((a, b) => a.price - b.price || hintRank(a.model) - hintRank(b.model));
+	const cheapest = cheaper[0]?.model;
+
+	/**
+	 * 4. The session's own model, ahead of the cost-ranked pick.
+	 *
+	 * Price is not evidence of suitability, and a name is barely better. On
+	 * OpenRouter the cheapest model in the catalog is `inclusionai/ling-2.6-flash`
+	 * at $0.01/M, which would otherwise become the security boundary for being
+	 * cheap. An attempt to gate that on the name carrying a known small-model word
+	 * failed on the same example — "flash" is in the name, because any vendor may
+	 * put it there; the word means "someone called this small", not "this family is
+	 * known good".
+	 *
+	 * So nothing chosen on price alone leads. Providers that *are* vetted get their
+	 * saving from the table above (which covers OpenRouter and every mainstream
+	 * provider); anywhere else the model the user already trusted for the real work
+	 * screens the calls — correct, merely not cheap — and `classifierModel` is
+	 * there for someone who wants otherwise.
+	 */
+	push(sessionModel, "session");
+
+	// 5. Last resort, for when even the session model cannot serve.
+	push(cheapest, "cheapest-in-provider");
+
+	// Nothing configured and no session model (a headless run with a bare
+	// registry) — take anything available rather than refusing outright.
+	if (candidates.length === 0) push(available[0], "session");
+
+	return candidates;
+}
+
+/**
+ * Whether an error means "this model is not usable on this account" — in which
+ * case stepping to the next candidate is right — as opposed to a transient
+ * failure, where switching models would hide a problem that is about to clear.
+ *
+ * "Quota" is deliberately matched only in its billing forms (`insufficient_quota`,
+ * "exceeded your current quota"): a bare match also caught per-minute rate-limit
+ * messages ("quota exceeded, retry in 60s"), permanently rejecting a healthy
+ * model for the whole session over a blip. Misreading billing as transient
+ * merely retries and blocks noisily; misreading a blip as permanent bricks the
+ * candidate — so uncertainty goes to transient.
+ */
+export function isModelUnavailableError(message: string): boolean {
+	return /\b(401|403|404)\b|not_found|not found|does not exist|(no|have|lacks?)\s+access|unauthoriz|forbidden|invalid[_ -]?model|model[_ -]?not|unsupported[_ -]?model|no such model|entitl|insufficient[_ -]?quota|exceeded your current quota|billing/i.test(
+		message,
+	);
+}
+
+/** One-line description for the notice and `/auto-mode config`. */
+export function describeCandidate(candidate: Candidate): string {
+	const name = `${candidate.model.provider}/${candidate.model.id}`;
+	switch (candidate.source) {
+		case "configured":
+			return `${name} (from autoMode.classifierModel)`;
+		case "role-profile": {
+			const where = modelIdentity(candidate.model).profile ?? candidate.model.provider;
+			return `${name} (classifier profile for ${where})`;
+		}
+		case "cheapest-in-provider": {
+			const where = modelIdentity(candidate.model).profile ?? candidate.model.provider;
+			return `${name} (cheapest available within ${where})`;
+		}
+		case "session": {
+			const where = modelIdentity(candidate.model).profile ?? candidate.model.provider;
+			return `${name} (this session's model — no vetted smaller model within ${where})`;
+		}
+	}
+}

package/extensions/auto-mode/paths.ts

@@ -0,0 +1,109 @@
+/**
+ * Path resolution and containment for the shell pre-gate (pure apart from fs
+ * reads).
+ *
+ * Two fixes over the sandbox this derives from:
+ *
+ * 1. **The symlink leaf is inspected** (review finding N9). The original's
+ *    ENOENT fallback joined literal basenames onto the nearest resolved
+ *    ancestor without ever lstat-ing the leaf, so `ln -s /outside/x link`
+ *    followed by `echo hi > link` resolved to `<project>/link` — inside the
+ *    project — while bash wrote through the symlink to `/outside/x`.
+ * 2. **Resolution failure is reported, not swallowed.** The original returned a
+ *    best-effort path on failure, so the caller could not tell a real
+ *    containment pass from a guess. Here an unresolvable path is `undefined`
+ *    and every caller treats that as "not provably contained".
+ */
+
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+
+/**
+ * Tools whose calls write to a path. Lives here — the lowest shared layer both
+ * the shell safety floor and the permission gate import — so the two write-gates
+ * share one source of truth for "which tools write" (was duplicated).
+ */
+export const WRITING_TOOLS = new Set(["edit", "write", "notebook_edit"]);
+
+export function isWritingTool(toolName: string): boolean {
+	return WRITING_TOOLS.has(toolName);
+}
+
+/** Case-folded on darwin/win32, where the filesystem is case-insensitive. */
+function normalize(target: string): string {
+	const normalized = resolve(target).replace(/\\/g, "/").replace(/\/+$/, "");
+	return process.platform === "linux" ? normalized : normalized.toLowerCase();
+}
+
+function tryRealpath(target: string): string | undefined {
+	try {
+		return realpathSync.native(target);
+	} catch {
+		try {
+			return realpathSync(target);
+		} catch {
+			return undefined;
+		}
+	}
+}
+
+/**
+ * Resolve a path for containment checks, following a symlink leaf that does not
+ * yet have a target. Returns undefined when nothing about the path can be
+ * resolved — callers must not treat that as contained.
+ */
+export function resolveForContainment(target: string): string | undefined {
+	const absolute = resolve(target);
+
+	const direct = tryRealpath(absolute);
+	if (direct) return normalize(direct);
+
+	// The leaf may be a dangling symlink: realpath fails on it, but writes still
+	// follow it. Read the link and resolve its target instead of assuming the
+	// literal path (N9).
+	try {
+		const stats = lstatSync(absolute);
+		if (stats.isSymbolicLink()) {
+			const linkTarget = readlinkSync(absolute);
+			const resolvedTarget = isAbsolute(linkTarget) ? linkTarget : resolve(dirname(absolute), linkTarget);
+			// One hop is enough: the target's own realpath covers the rest of a chain.
+			return resolveForContainment(resolvedTarget) ?? normalize(resolvedTarget);
+		}
+	} catch {
+		// Does not exist yet — fall through to ancestor resolution below.
+	}
+
+	// A path being created (`> newfile`): resolve the nearest existing ancestor
+	// and re-attach the tail, so a symlinked *parent* directory is still followed.
+	const tail: string[] = [];
+	let cursor = absolute;
+	for (;;) {
+		const parent = dirname(cursor);
+		if (parent === cursor) return undefined;
+		tail.unshift(basename(cursor));
+		const realParent = tryRealpath(parent);
+		if (realParent) return normalize(join(realParent, ...tail));
+		cursor = parent;
+	}
+}
+
+/** True only when `target` is provably at or under `base`. */
+export function isWithin(base: string, target: string): boolean {
+	const normalizedBase = normalize(base);
+	const normalizedTarget = normalize(target);
+	return normalizedTarget === normalizedBase || normalizedTarget.startsWith(`${normalizedBase}/`);
+}
+
+/**
+ * Expand a leading `~`, then resolve relative to `cwd`. Kept separate from
+ * resolveForContainment so callers can report the *original* token in messages:
+ * a resolved path can embed an expanded environment-variable value, and echoing
+ * that back to the model leaks the secret it was meant to protect (review
+ * finding N18).
+ */
+export function toAbsolute(cwd: string, token: string, home: string): string {
+	if (token === "~") return home;
+	if (token.startsWith("~/")) return resolve(home, token.slice(2));
+	if (isAbsolute(token)) return resolve(token);
+	return resolve(cwd, token);
+}