one-code-extension 0.1.0

package/extensions/auto-mode/classifier.ts

@@ -0,0 +1,388 @@
+/**
+ * The classifier call itself — the one file here that talks to a provider.
+ *
+ * A one-shot `completeSimple` rather than an agent session: the classifier gets
+ * no tools, no session, and no history beyond the user messages it is handed, so
+ * there is nothing for it to be talked into doing. Its only output is a verdict.
+ *
+ * Model selection prefers a small fast model (Claude Code uses a Sonnet-class
+ * model for this), overridable with `autoMode.classifierModel`, falling back to
+ * the session's own model so auto mode still works on a single-model setup.
+ */
+
+import type { Model, Api } from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { AutoModeConfig } from "./config.ts";
+import { buildClassifierPrompt, type ClassifyRequest, type ClassifyVerdict, parseVerdict } from "./prompt.ts";
+import {
+	type Candidate,
+	classifierCandidates,
+	describeCandidate,
+	isModelUnavailableError,
+} from "./model-select.ts";
+import { indexRules } from "./rules.ts";
+
+/** A slow classifier stalls every tool call, so the wait is capped. */
+export const CLASSIFIER_TIMEOUT_MS = 30_000;
+
+/**
+ * A pinned model that times out this many calls in a row is unpinned, so a model
+ * that was fast when first chosen but has since fallen behind demand does not
+ * stay the session's classifier forever. The next call re-runs selection.
+ */
+export const ROTATE_AFTER_TIMEOUTS = 2;
+
+/**
+ * Whether a failure is our own classifier timeout (or an equivalent abort/stall)
+ * rather than a substantive provider error. A timeout is transient — worth a
+ * retry and worth stepping to another candidate — where a 500 or a bad request
+ * is not. A *user* cancel also aborts, so callers must rule that out first
+ * (`deps.signal?.aborted`) before treating an abort as a timeout.
+ */
+export function isClassifierTimeout(message: string): boolean {
+	// `\babort` (no trailing boundary) so "abort", "aborted", and "aborting" all
+	// match — the observed message is "Request aborted", which a trailing \b
+	// would miss. The others are whole words.
+	return /\babort|\btimed?\s*out\b|\btimeout\b|\betimedout\b|\bdeadline\b/i.test(message);
+}
+
+/**
+ * Which model the classifier settled on, and which candidates turned out to be
+ * unusable. Owned by the caller so this module stays stateless, and so the
+ * choice is *pinned*: re-resolving per call would let a registry refresh swap
+ * classifiers mid-session, and would re-try a model already known to be dead.
+ */
+export interface ClassifierState {
+	pinned?: Model<Api>;
+	/** `provider/id` of candidates that failed as unusable. */
+	rejected: Set<string>;
+	/** Notices already delivered, so a per-call warning is not repeated per call. */
+	notified: Set<string>;
+	/**
+	 * Consecutive calls the pinned model has timed out on. Reset by any success;
+	 * at ROTATE_AFTER_TIMEOUTS the pin is released so the session re-picks rather
+	 * than staying bound to a model that has fallen behind demand.
+	 */
+	timeoutStreak: number;
+}
+
+export function createClassifierState(): ClassifierState {
+	return { rejected: new Set(), notified: new Set(), timeoutStreak: 0 };
+}
+
+export interface ClassifierDeps {
+	registry: ModelRegistry;
+	sessionModel: Model<Api> | undefined;
+	config: AutoModeConfig;
+	signal?: AbortSignal;
+	state: ClassifierState;
+	/** Tell the user something once — which model is in use, or that theirs is dead. */
+	onNotice?: (message: string, level: "info" | "warning") => void;
+}
+
+/** The candidate chain, minus anything already found unusable this session. */
+function remainingCandidates(deps: ClassifierDeps): Candidate[] {
+	const all = classifierCandidates({
+		available: deps.registry.getAvailable(),
+		sessionModel: deps.sessionModel,
+		configured: deps.config.classifierModel,
+	});
+	const usable = all.filter((entry) => !deps.state.rejected.has(`${entry.model.provider}/${entry.model.id}`));
+	if (usable.length > 0) return usable;
+	// If everything has been rejected, the session model is still worth one more
+	// attempt: a gate that stops asking has stopped gating. It has to be the
+	// session model specifically — the *last* chain entry is the cost-ranked
+	// pick, which nothing price-chosen should lead, let alone be the sole retry.
+	const session = all.filter((entry) => entry.source === "session");
+	return session.length > 0 ? session : all.slice(-1);
+}
+
+function notifyOnce(deps: ClassifierDeps, key: string, message: string, level: "info" | "warning") {
+	if (deps.state.notified.has(key)) return;
+	deps.state.notified.add(key);
+	deps.onNotice?.(message, level);
+}
+
+/**
+ * Ask the classifier about one tool call. Every failure path — no model, no
+ * credentials, timeout, provider error, unparseable reply — returns a block.
+ * An approval gate that cannot reach its classifier has not approved anything.
+ */
+export async function classify(request: ClassifyRequest, deps: ClassifierDeps): Promise<ClassifyVerdict> {
+	const candidates = remainingCandidates(deps);
+	if (candidates.length === 0) {
+		return { decision: "block", reason: "No model is available to run the auto-mode classifier.", tier: "unmatched" };
+	}
+
+	// A configured model that matches nothing available would otherwise fall
+	// through in silence, leaving the user believing their setting is in force
+	// while something else screens their calls.
+	const configured = deps.config.classifierModel;
+	if (configured && !candidates.some((entry) => entry.source === "configured")) {
+		notifyOnce(
+			deps,
+			`unresolved:${configured}`,
+			`autoMode.classifierModel is set to "${configured}", which is not an available model — check the name and that its provider is authenticated. Auto mode is using ${describeCandidate(candidates[0])} instead.`,
+			"warning",
+		);
+	}
+
+	const index = indexRules(deps.config);
+	const { system, user } = buildClassifierPrompt(request, deps.config, index);
+
+	// A model already pinned this session is tried first, so the classifier does
+	// not change under the session while the pin is healthy. The rest of the
+	// chain stays behind it: a pinned model can be withdrawn mid-session, and
+	// the same call must then step onward rather than fail every call forever.
+	const pinned = deps.state.pinned;
+	const attempts = pinned
+		? [
+				{ model: pinned, source: "session" as const },
+				...candidates.filter((entry) => entry.model.provider !== pinned.provider || entry.model.id !== pinned.id),
+			]
+		: candidates;
+
+	// Rejecting a model releases its pin: without that, a model withdrawn
+	// mid-session would stay pinned, be the only candidate tried on every later
+	// call, and turn the gate into a permanent block until restart.
+	const reject = (key: string) => {
+		deps.state.rejected.add(key);
+		if (deps.state.pinned && `${deps.state.pinned.provider}/${deps.state.pinned.id}` === key) {
+			deps.state.pinned = undefined;
+		}
+	};
+
+	let lastError = "";
+	let sawTimeout = false;
+	for (const candidate of attempts) {
+		const model = candidate.model;
+		const key = `${model.provider}/${model.id}`;
+
+		const auth = await deps.registry.getApiKeyAndHeaders(model);
+		if (!auth.ok) {
+			reject(key);
+			lastError = auth.error;
+			continue;
+		}
+
+		// Some pi builds resolve a per-provider baseUrl alongside the key; it is not
+		// in every published version of the auth type, so it is read defensively.
+		const baseUrl = (auth as { baseUrl?: string }).baseUrl;
+
+		const attempt = (maxTokens: number) => {
+			const timeout = AbortSignal.timeout(CLASSIFIER_TIMEOUT_MS);
+			return completeSimple(
+				baseUrl ? ({ ...model, baseUrl } as Model<Api>) : model,
+				{ systemPrompt: system, messages: [{ role: "user", content: user, timestamp: Date.now() }] },
+				{
+					apiKey: auth.apiKey,
+					headers: auth.headers,
+					env: auth.env,
+					signal: deps.signal ? AbortSignal.any([deps.signal, timeout]) : timeout,
+					...(process.env.CC_AUTO_MODE_DEBUG === "2"
+						? {
+								onPayload: (payload: unknown) => {
+									const body = payload as { system?: Array<Record<string, unknown>> };
+									const blocks = (body.system ?? []).map(
+										(b) =>
+											`{keys=${Object.keys(b).join(",")} textLen=${String((b as { text?: string }).text ?? "").length} cache=${JSON.stringify((b as { cache_control?: unknown }).cache_control)}}`,
+									);
+									process.stderr.write(`[auto-mode payload] systemBlocks=${blocks.join(" ")}\n`);
+									return undefined;
+								},
+							}
+						: {}),
+					maxTokens,
+					// `reasoning` is deliberately omitted: pi turns thinking off entirely
+					// when it is absent, which is what a classifier wants (fast, cheap,
+					// deterministic). Passing even "minimal" enables thinking, and the
+					// resulting budget is derived from maxTokens — at 512 that lands under
+					// Anthropic's 1024-token floor and every request 400s, which the gate
+					// then correctly but uselessly reports as a block.
+					//
+					// `temperature` is likewise NOT passed. It looks free — a classifier
+					// wants determinism — but it is deprecated on Claude Sonnet 5 and
+					// unsupported on Opus 4.7+, and pi's compat data still advertises it,
+					// so the request 400s and the gate blocks every single call. Several
+					// OpenAI reasoning models reject it too. A gate that must work across
+					// 38 providers cannot afford an option that fails closed on some of
+					// them for a property it does not need.
+					cacheRetention: "long",
+				},
+			);
+		};
+
+		// A cut-off reply (stopReason "length") voids the verdict, so retry once with
+		// real headroom. Used for both the initial call and the post-timeout retry.
+		const attemptWithLengthRetry = async () => {
+			let reply = await attempt(1024);
+			if (reply.stopReason === "length") reply = await attempt(4096);
+			return reply;
+		};
+
+		let failure: string | undefined;
+		try {
+			// A verdict is one JSON object, but the cap needs headroom over "one
+			// JSON object": models that reasoning cannot be disabled on (deepseek
+			// via opencode, observed live) burn output budget on deliberation —
+			// most on exactly the risky calls that deserve it — and a truncated
+			// reply voids the verdict. So a cut-off reply gets one retry with real
+			// headroom and a fresh timeout; the cap bounds runaway output, not
+			// typical cost, since replies still stop at the closing brace.
+			let reply = await attemptWithLengthRetry();
+
+			// One retry on a timeout, before giving up on this model. A stall under
+			// load usually clears on a second try; a model that is simply too slow
+			// times out again, and the loop then steps to the next candidate (or, if
+			// none remains, the call falls through to a user prompt). A *user* cancel
+			// also aborts — that is not a timeout and must not be retried.
+			if (
+				(reply.stopReason === "aborted" || reply.stopReason === "error") &&
+				!deps.signal?.aborted &&
+				isClassifierTimeout(reply.errorMessage ?? reply.stopReason ?? "")
+			) {
+				reply = await attemptWithLengthRetry();
+			}
+
+			if (reply.stopReason === "error" || reply.stopReason === "aborted") {
+				failure = reply.errorMessage ?? reply.stopReason;
+			} else if (reply.stopReason === "length") {
+				// Still cut off at 4096 — same treatment as an unparseable reply (a
+				// verdict that cannot be read approved nothing), but named, because
+				// "unreadable response" sent a live debugging session hunting for
+				// JSON bugs when the real cause was the output budget.
+				if (process.env.CC_AUTO_MODE_DEBUG) {
+					const u = reply.usage as { input?: number; output?: number; reasoning?: number } | undefined;
+					process.stderr.write(
+						`[auto-mode] ${key} ${request.toolName} → verdict truncated at maxTokens ` +
+							`(in=${u?.input ?? "?"} out=${u?.output ?? "?"} reasoning=${u?.reasoning ?? 0})\n`,
+					);
+				}
+				return {
+					decision: "block",
+					reason:
+						"The approval classifier's reply was cut off by its output limit before the verdict completed — its analysis ran too long. If this keeps happening, pin a stronger classifier model with /auto-mode model.",
+					tier: "unmatched",
+				};
+			} else {
+				const text = reply.content
+					.filter((block): block is { type: "text"; text: string } => block.type === "text")
+					.map((block) => block.text)
+					.join("");
+				const verdict = parseVerdict(text, index, request.userMessages);
+
+				// A verdict came back, so the timeout streak that might have been
+				// building is over.
+				deps.state.timeoutStreak = 0;
+
+				// Pin on the first success, so the classifier cannot change under the
+				// session and a working model is not re-litigated per call.
+				if (!deps.state.pinned) {
+					deps.state.pinned = model;
+					notifyOnce(deps, `using:${key}`, `Auto mode is screening calls with ${describeCandidate(candidate)}.`, "info");
+				}
+
+				// Allows carry no reason, so without this the permissive direction is
+				// invisible — which is the harder one to notice and the more costly one
+				// to get wrong. `CC_AUTO_MODE_DEBUG=1` puts the raw reply on stderr.
+				if (process.env.CC_AUTO_MODE_DEBUG) {
+					const u = reply.usage as
+						| {
+								input?: number;
+								output?: number;
+								reasoning?: number;
+								cacheRead?: number;
+								cacheWrite?: number;
+								cost?: unknown;
+						  }
+						| undefined;
+					const cost = u?.cost;
+					const spend =
+						cost && typeof cost === "object"
+							? Object.entries(cost as Record<string, unknown>)
+									.filter(([, value]) => typeof value === "number" && value > 0)
+									.map(([name, value]) => `${name}=$${(value as number).toFixed(6)}`)
+									.join(" ")
+							: "";
+					process.stderr.write(
+						`[auto-mode] ${key} ${request.toolName} → ${verdict.decision}${verdict.ruleId ? ` (${verdict.ruleId})` : ""}\n` +
+							`  usage: in=${u?.input ?? "?"} out=${u?.output ?? "?"} reasoning=${u?.reasoning ?? 0} cacheRead=${u?.cacheRead ?? 0} cacheWrite=${u?.cacheWrite ?? 0} ${spend}\n` +
+							`  raw: ${text.replace(/\s+/g, " ").slice(0, 400)}\n`,
+					);
+				}
+				return verdict;
+			}
+		} catch (error) {
+			failure = error instanceof Error ? error.message : String(error);
+		}
+
+		lastError = failure ?? "unknown error";
+
+		// A user cancel aborts the same way a timeout does. It is not a failure to
+		// route around — the user asked to stop, so stop.
+		if (deps.signal?.aborted) {
+			return { decision: "block", reason: "Auto-mode classification was cancelled.", tier: "unmatched" };
+		}
+
+		// A timeout (after the one retry above) is transient, so the model is NOT
+		// rejected — it may be fine on the next call. Instead we step to the next
+		// candidate, which is a different model of the *same or cheaper* price in
+		// the same provider (the chain is privacy- and budget-contained upstream).
+		// A pinned model that keeps timing out is unpinned so the session re-picks.
+		if (isClassifierTimeout(lastError)) {
+			sawTimeout = true;
+			if (deps.state.pinned && `${deps.state.pinned.provider}/${deps.state.pinned.id}` === key) {
+				deps.state.timeoutStreak += 1;
+				if (deps.state.timeoutStreak >= ROTATE_AFTER_TIMEOUTS) deps.state.pinned = undefined;
+			}
+			continue;
+		}
+
+		// A model that is simply not usable here is worth stepping over. Any other
+		// transient failure is not: switching models would paper over something
+		// about to clear, so that surfaces as a block and the same model is tried
+		// again next call.
+		if (!isModelUnavailableError(lastError)) {
+			return {
+				decision: "block",
+				reason: `Auto-mode classifier could not be reached (${lastError}).`,
+				tier: "unmatched",
+			};
+		}
+
+		reject(key);
+		const isConfigured = candidate.source === "configured";
+		notifyOnce(
+			deps,
+			`rejected:${key}`,
+			isConfigured
+				? `Auto mode cannot use ${key} from autoMode.classifierModel (${lastError}). Set a different model in ~/.claude/settings.json.`
+				: `Auto mode cannot use ${key} as its classifier (${lastError}); trying another model. Set autoMode.classifierModel in ~/.claude/settings.json to choose one.`,
+			"warning",
+		);
+	}
+
+	// Every candidate timed out (with a retry each) and none was reachable in
+	// time. This is NOT a judgement that the call is unsafe — it was never
+	// screened — so it is surfaced as its own tier. The gate turns a `timeout`
+	// into a user prompt where it can (there is someone to ask), and only blocks
+	// outright when running non-interactively.
+	if (sawTimeout) {
+		return {
+			decision: "block",
+			tier: "timeout",
+			reason:
+				"Auto mode could not screen this call in time — the approval classifier timed out, so the call was not judged either way. " +
+				"Approve it if you recognise it as safe, or pin a faster classifier with /auto-mode model.",
+		};
+	}
+
+	// Every candidate was unusable — say which knob fixes it rather than leaving
+	// the user with a gate that blocks everything for no stated reason.
+	return {
+		decision: "block",
+		reason: `No usable auto-mode classifier model (last error: ${lastError}). Set autoMode.classifierModel in ~/.claude/settings.json.`,
+		tier: "unmatched",
+	};
+}

package/extensions/auto-mode/config.ts

@@ -0,0 +1,237 @@
+/**
+ * `autoMode` settings loading (pure fs), Claude Code compatible.
+ *
+ * ## Which files are read, and why that list is short
+ *
+ * User settings (`~/.claude/settings.json`) and managed settings only — **never
+ * the project's `.claude/settings.json` or `.claude/settings.local.json`**. Both
+ * live in the repository, so a checked-in file or a build step that writes one
+ * could otherwise hand itself classifier allow rules and switch off the gate
+ * that is meant to contain it. Claude Code made the same exclusion (it dropped
+ * `settings.local.json` in v2.1.207); this is that property, not an omission.
+ *
+ * `"$defaults"` in any list splices the built-in rules in at that position, so
+ * users keep inheriting updates. Omitting it replaces the list wholesale, which
+ * is a real and occasionally correct choice — `/auto-mode config` shows the
+ * result either way.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DEFAULT_ALLOW, DEFAULT_ENVIRONMENT, DEFAULT_HARD_DENY, DEFAULT_SOFT_DENY } from "./defaults.ts";
+
+export interface AutoModeConfig {
+	environment: string[];
+	allow: string[];
+	soft_deny: string[];
+	hard_deny: string[];
+	/** Suspend narrow Bash allow rules so every shell command reaches the classifier. */
+	classifyAllShell: boolean;
+	/** `provider/model-id` override for the classifier model. */
+	classifierModel?: string;
+	/** Append every gate decision to auto-mode-decisions.jsonl next to the session files. */
+	logDecisions: boolean;
+}
+
+interface AutoModeSettingsFile {
+	autoMode?: {
+		environment?: unknown;
+		allow?: unknown;
+		soft_deny?: unknown;
+		hard_deny?: unknown;
+		classifyAllShell?: unknown;
+		classifierModel?: unknown;
+		logDecisions?: unknown;
+	};
+	[key: string]: unknown;
+}
+
+const DEFAULTS_TOKEN = "$defaults";
+
+/** Managed-settings locations, highest authority, matching Claude Code's paths. */
+function managedSettingsPaths(): string[] {
+	if (process.platform === "darwin") return ["/Library/Application Support/ClaudeCode/managed-settings.json"];
+	if (process.platform === "win32") return ["C:\\ProgramData\\ClaudeCode\\managed-settings.json"];
+	return ["/etc/claude-code/managed-settings.json"];
+}
+
+/** The files `autoMode` is read from, lowest precedence first. */
+export function autoModeSettingsPaths(home: string): string[] {
+	return [join(home, ".claude", "settings.json"), ...managedSettingsPaths()];
+}
+
+function readFile(path: string, diagnostics: string[]): AutoModeSettingsFile | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")) as AutoModeSettingsFile;
+	} catch (error) {
+		// Swallowing this silently is how a user ends up believing rules are in
+		// force that the gate never loaded — the file is still skipped (the gate
+		// must not die on a typo), but the skip is reported.
+		diagnostics.push(`${path}: invalid JSON, autoMode settings in it are ignored (${(error as Error).message})`);
+		return undefined;
+	}
+}
+
+const KNOWN_AUTO_MODE_KEYS = new Set([
+	"environment",
+	"allow",
+	"soft_deny",
+	"hard_deny",
+	"classifyAllShell",
+	"classifierModel",
+	"logDecisions",
+]);
+
+const RULE_LIST_KEYS = ["environment", "allow", "soft_deny", "hard_deny"] as const;
+
+/**
+ * Shape problems in one file's `autoMode` block, as human-readable lines.
+ * Purely advisory: loading stays lenient (a wrong-typed field is skipped, not
+ * fatal), but skipped-because-mistyped must be visible in `/auto-mode config`
+ * or it reads as the gate ignoring the user's settings.
+ */
+function validateAutoModeBlock(block: Record<string, unknown>, path: string, diagnostics: string[]): void {
+	for (const key of Object.keys(block)) {
+		if (!KNOWN_AUTO_MODE_KEYS.has(key)) diagnostics.push(`${path}: unknown autoMode key "${key}" is ignored`);
+	}
+	for (const key of RULE_LIST_KEYS) {
+		const value = block[key];
+		if (value === undefined) continue;
+		if (!Array.isArray(value)) {
+			diagnostics.push(`${path}: autoMode.${key} must be an array of strings — ignored`);
+			continue;
+		}
+		for (const [position, entry] of value.entries()) {
+			if (typeof entry !== "string" || entry.trim().length === 0) {
+				diagnostics.push(`${path}: autoMode.${key}[${position}] is not a non-empty string — dropped`);
+			}
+		}
+		const strings = value.filter((entry): entry is string => typeof entry === "string");
+		if (strings.length > 0 && !strings.some((entry) => entry.trim() === DEFAULTS_TOKEN)) {
+			diagnostics.push(
+				`${path}: autoMode.${key} omits "${DEFAULTS_TOKEN}", so it REPLACES the built-in ${key} list rather than extending it`,
+			);
+		}
+	}
+	for (const key of ["classifyAllShell", "logDecisions"] as const) {
+		if (block[key] !== undefined && typeof block[key] !== "boolean") {
+			diagnostics.push(`${path}: autoMode.${key} must be a boolean — ignored`);
+		}
+	}
+	if (
+		block.classifierModel !== undefined &&
+		(typeof block.classifierModel !== "string" || block.classifierModel.trim().length === 0)
+	) {
+		diagnostics.push(`${path}: autoMode.classifierModel must be a "provider/model-id" string — ignored`);
+	}
+}
+
+function stringArray(value: unknown): string[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	return value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
+}
+
+/**
+ * Splice `$defaults` into a user list. Entries from separate scopes are
+ * additive: a developer can extend a managed list but not remove from it.
+ */
+export function spliceDefaults(entries: string[] | undefined, defaults: string[]): string[] {
+	if (!entries) return [...defaults];
+	const out: string[] = [];
+	for (const entry of entries) {
+		if (entry.trim() === DEFAULTS_TOKEN) out.push(...defaults);
+		else out.push(entry);
+	}
+	return out;
+}
+
+export interface AutoModeConfigLoad {
+	config: AutoModeConfig;
+	/** Problems found while loading, for `/auto-mode config`. Empty when clean. */
+	diagnostics: string[];
+}
+
+export function loadAutoModeConfigWithDiagnostics(home: string): AutoModeConfigLoad {
+	const diagnostics: string[] = [];
+	const collected: {
+		environment?: string[];
+		allow?: string[];
+		soft_deny?: string[];
+		hard_deny?: string[];
+		classifyAllShell?: boolean;
+		classifierModel?: string;
+		logDecisions?: boolean;
+	} = {};
+
+	for (const path of autoModeSettingsPaths(home)) {
+		const file = readFile(path, diagnostics);
+		const block = file?.autoMode;
+		if (file !== undefined && "autoMode" in file && (typeof block !== "object" || block === null || Array.isArray(block))) {
+			diagnostics.push(`${path}: autoMode must be an object — ignored`);
+			continue;
+		}
+		if (!block) continue;
+		validateAutoModeBlock(block as Record<string, unknown>, path, diagnostics);
+		for (const key of RULE_LIST_KEYS) {
+			const parsed = stringArray(block[key]);
+			// Additive across scopes: a later scope extends rather than replaces,
+			// so managed entries cannot be dropped by a user file.
+			if (parsed) collected[key] = [...(collected[key] ?? []), ...parsed];
+		}
+		if (typeof block.classifyAllShell === "boolean") collected.classifyAllShell = block.classifyAllShell;
+		if (typeof block.logDecisions === "boolean") collected.logDecisions = block.logDecisions;
+		if (typeof block.classifierModel === "string" && block.classifierModel.trim()) {
+			collected.classifierModel = block.classifierModel.trim();
+		}
+	}
+
+	return {
+		config: {
+			environment: spliceDefaults(collected.environment, DEFAULT_ENVIRONMENT),
+			allow: spliceDefaults(collected.allow, DEFAULT_ALLOW),
+			soft_deny: spliceDefaults(collected.soft_deny, DEFAULT_SOFT_DENY),
+			hard_deny: spliceDefaults(collected.hard_deny, DEFAULT_HARD_DENY),
+			classifyAllShell: collected.classifyAllShell ?? false,
+			classifierModel: collected.classifierModel,
+			logDecisions: collected.logDecisions ?? false,
+		},
+		diagnostics,
+	};
+}
+
+export function loadAutoModeConfig(home: string): AutoModeConfig {
+	return loadAutoModeConfigWithDiagnostics(home).config;
+}
+
+/**
+ * Persist `autoMode.classifierModel` in the *user* settings file, preserving
+ * every other key. `undefined` removes the setting. Always user scope: this is
+ * the knob that may move the classifier to another provider, so it lives where
+ * only the user writes — never in a project file (see the module comment).
+ *
+ * Unlike loading, this throws on a malformed file: a lenient read merely skips
+ * rules, but a lenient write would replace the user's whole settings file with
+ * only ours.
+ */
+export function persistClassifierModel(spec: string | undefined, home: string): void {
+	const path = join(home, ".claude", "settings.json");
+	let file: Record<string, unknown> = {};
+	if (existsSync(path)) {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			throw new Error(`${path}: root must be a JSON object`);
+		}
+		file = parsed as Record<string, unknown>;
+	}
+	const block =
+		typeof file.autoMode === "object" && file.autoMode !== null && !Array.isArray(file.autoMode)
+			? (file.autoMode as Record<string, unknown>)
+			: {};
+	if (spec === undefined) delete block.classifierModel;
+	else block.classifierModel = spec;
+	if (Object.keys(block).length === 0) delete file.autoMode;
+	else file.autoMode = block;
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`);
+}

package/extensions/auto-mode/decision-log.ts

@@ -0,0 +1,60 @@
+/**
+ * Auto mode's decision log (pure apart from the append).
+ *
+ * Opt-in via `autoMode.logDecisions: true`. One JSONL line per gate decision —
+ * who decided (pre-gate, floor, classifier, the user at a prompt), what about,
+ * and on what grounds — in `auto-mode-decisions.jsonl` next to the session
+ * files, with a sessionId on each line.
+ *
+ * This exists because the calibration workflow is real: both regressions this
+ * feature has had were caught by reading raw verdicts, and stderr under
+ * CC_AUTO_MODE_DEBUG only helps when someone thought to set it *before* the
+ * session. A standing log makes "what has the gate been deciding, and which
+ * direction is drifting" answerable after the fact. The permissive direction
+ * especially: allows are invisible in the UI by design, so this file is the
+ * only complete record of them.
+ *
+ * Logging must never break the gate, so failures are swallowed: a gate that
+ * blocks tool calls because its diary is unwritable has its priorities
+ * backwards.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface DecisionEntry {
+	ts: string;
+	sessionId?: string;
+	tool: string;
+	/** Command or path, clipped — never tool output. */
+	subject: string;
+	outcome: "allow" | "block" | "prompt";
+	/** Which layer decided. */
+	source: "pre-gate" | "classifier" | "floor" | "user" | "review";
+	tier?: string;
+	ruleId?: string;
+	reason?: string;
+	/** The classifier's own commentary, attributed (see prompt.ts). */
+	raw?: string;
+	/** `provider/id` of the model that produced a classifier verdict. */
+	model?: string;
+}
+
+const SUBJECT_LIMIT = 300;
+
+export function decisionEntry(entry: Omit<DecisionEntry, "ts" | "subject"> & { subject: string }): DecisionEntry {
+	return {
+		...entry,
+		ts: new Date().toISOString(),
+		subject: entry.subject.length > SUBJECT_LIMIT ? `${entry.subject.slice(0, SUBJECT_LIMIT)}…` : entry.subject,
+	};
+}
+
+export function appendDecision(file: string, entry: DecisionEntry): void {
+	try {
+		mkdirSync(dirname(file), { recursive: true });
+		appendFileSync(file, `${JSON.stringify(entry)}\n`);
+	} catch {
+		// Logging must never break the gate.
+	}
+}