one-code-extension 0.4.0 → 0.5.0

package/extensions/lib/claude-external-includes.ts

@@ -0,0 +1,68 @@
+/** Claude Code's project-scoped external instruction consent; pure fs/text, no pi imports. */
+import { readJsonFile } from "./atomic-write.ts";
+import { oneCodeProjectRoot, oneCodeProjectSettingsPathFor, readSettingsForWrite, writeSettings } from "./one-code-settings.ts";
+import { comparablePath, tildify } from "./paths.ts";
+import { escapeControlText } from "./terminal-text.ts";
+
+export const EXTERNAL_INCLUDES_TITLE = "Allow external CLAUDE.md file imports?";
+export const EXTERNAL_INCLUDES_YES = "Yes, allow external imports";
+export const EXTERNAL_INCLUDES_NO = "No, disable external imports";
+export const EXTERNAL_INCLUDES_SETTING = "External CLAUDE.md includes";
+/**
+ * `/config` with nothing to show. Claude Code's /config is a full settings
+ * panel and hides this row when there are no external includes; One Code's
+ * holds only this row so far (decisions/tools.md), so the empty case names
+ * where the other settings live instead of ending the command.
+ */
+export const EXTERNAL_INCLUDES_NONE =
+	"No external CLAUDE.md includes in this project, so /config has nothing to change. Other settings: /settings (pi's settings), /model, /permissions, /memory.";
+
+export interface ExternalIncludesApproval {
+	approved: boolean;
+	warningShown: boolean;
+}
+
+/**
+ * The project root an answer was given for. The settings file's slug is lossy
+ * (`my_app` and `my-app` share one file), so the answer counts only for this
+ * exact root; an answer recorded without one is asked again.
+ */
+const APPROVAL_ROOT_KEY = "claudeMdExternalIncludesRoot";
+
+/** Only One Code's out-of-checkout project state grants consent, never merged project settings. */
+export function readExternalIncludesApproval(cwd: string, home: string): ExternalIncludesApproval {
+	const root = oneCodeProjectRoot(cwd);
+	const file = readJsonFile<Record<string, unknown>>(oneCodeProjectSettingsPathFor(root, home));
+	const recorded = file?.[APPROVAL_ROOT_KEY];
+	if (!file || typeof recorded !== "string" || comparablePath(recorded) !== comparablePath(root)) return { approved: false, warningShown: false };
+	return {
+		approved: file.hasClaudeMdExternalIncludesApproved === true,
+		warningShown: file.hasClaudeMdExternalIncludesWarningShown === true,
+	};
+}
+
+/** Both answers are remembered, and cover future imports, not just the files in the preview. */
+export function persistExternalIncludesApproval(cwd: string, home: string, approved: boolean): void {
+	const root = oneCodeProjectRoot(cwd);
+	const path = oneCodeProjectSettingsPathFor(root, home);
+	writeSettings(path, {
+		...readSettingsForWrite(path),
+		hasClaudeMdExternalIncludesApproved: approved,
+		hasClaudeMdExternalIncludesWarningShown: true,
+		[APPROVAL_ROOT_KEY]: root,
+	});
+}
+
+/** The dialog text; pi's plain select carries the body in its multiline title, including over RPC. */
+export function externalIncludesDialog(paths: string[], home: string): string {
+	const shown = paths.length <= 8 ? paths : paths.slice(0, 6);
+	const hidden = paths.length - shown.length;
+	const preview = shown.map((path) => `  ${escapeControlText(tildify(path, home))}`);
+	if (hidden) preview.push(`  … +${hidden} ${hidden === 1 ? "import" : "imports"} not shown.`, "  Yes covers those too, plus any this project adds later.");
+	return [
+		EXTERNAL_INCLUDES_TITLE,
+		"This project's CLAUDE.md or .claude/rules imports files outside the current working directory. Never allow this for third-party repositories.",
+		...(paths.length ? [`External imports:\n${preview.join("\n")}`] : []),
+		"Important: Only use One Code with files you trust. Accessing untrusted files may pose security risks.",
+	].join("\n\n");
+}

package/extensions/lib/claude-id.ts

@@ -0,0 +1,22 @@
+/**
+ * Claude model ids in any provider's spelling (pure, no imports), for the
+ * gates that must not pull in the tier module's catalog graph.
+ */
+
+/**
+ * A Claude model id in any provider's spelling (`claude-opus-5-5`,
+ * `claude-haiku-4-5-20251001`, `anthropic/claude-sonnet-5.5`, Bedrock's
+ * `us.anthropic.claude-fable-5-1-v1`): family, major, and minor when the id
+ * has one. A dated suffix is never read as the minor version. Undefined for
+ * anything else. `parseClaudeVersion` (model-tier.ts) stays first-party only, for the gates.
+ */
+export function parseClaudeId(id: string): { family: "opus" | "sonnet" | "haiku" | "fable"; major: number; minor?: number } | undefined {
+	const match = id.match(/(?:^|[/.])claude-(opus|sonnet|haiku|fable)-(\d+)(?:[-.](\d{1,2}))?(?=$|[-@:[])/);
+	if (!match) return undefined;
+	return { family: match[1] as "opus" | "sonnet" | "haiku" | "fable", major: Number(match[2]), ...(match[3] ? { minor: Number(match[3]) } : {}) };
+}
+
+/** The Claude family of a model id in any provider's spelling. */
+export function claudeFamily(id: string): "opus" | "sonnet" | "haiku" | "fable" | undefined {
+	return parseClaudeId(id)?.family;
+}

package/extensions/lib/claude-rules.ts

@@ -0,0 +1,323 @@
+/** Claude Code 2.1.289 rule parsing/discovery. Pure filesystem/text helpers; no pi state. */
+import { lstatSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative } from "node:path";
+import ignore, { type Ignore } from "ignore";
+import { Lexer, type Token } from "marked";
+import { parse as parseYaml } from "yaml";
+import { absoluteFrom, comparablePath, expandTilde, forwardSlashes, isPathAtOrUnder, isRelativeInside, tryRealpath } from "./paths.ts";
+
+/** pO/Oee: instruction files larger than 4 MiB are skipped, never truncated. */
+export const MAX_INSTRUCTION_BYTES = 4_194_304;
+
+export interface RuleFile {
+	path: string;
+	key: string;
+	content: string;
+	globs?: string[];
+	/** Import/link provenance for the startup external-includes warning. */
+	parent?: string;
+	linkedFrom?: string;
+}
+
+/** f_t/H in the binary: comma lists and brace alternatives, not numeric brace ranges. */
+export function splitRulePaths(value: unknown): string[] {
+	const budget = { results: 1000, bytes: 4_194_304 };
+	const expand = (pattern: string): string[] => {
+		if (!pattern.includes("{")) return [pattern];
+		const result: string[] = [];
+		const pending = [pattern];
+		for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+			const match = next.match(/^([^{]*)\{([^}]+)\}(.*)$/);
+			if (!match) { result.push(next); continue; }
+			const alternatives = match[2].split(",").map((part) => part.trim());
+			budget.bytes -= next.length;
+			const count = result.length + pending.length + alternatives.length;
+			if (budget.bytes < 0 || count > budget.results || count * pattern.length > budget.bytes) return [pattern];
+			for (let i = alternatives.length - 1; i >= 0; i--) pending.push(match[1] + alternatives[i] + match[3]);
+		}
+		budget.results -= result.length;
+		budget.bytes -= result.length * pattern.length;
+		return result;
+	};
+	const split = (input: unknown): string[] => {
+		if (Array.isArray(input)) return input.flatMap(split);
+		if (typeof input !== "string") return [];
+		const parts: string[] = [];
+		let part = "", depth = 0;
+		for (const char of input) {
+			if (char === "{") depth++;
+			if (char === "}") depth--;
+			if (char === "," && depth === 0) { if (part.trim()) parts.push(part.trim()); part = ""; }
+			else part += char;
+		}
+		if (part.trim()) parts.push(part.trim());
+		return parts.flatMap(expand);
+	};
+	return split(value);
+}
+
+/** Fs retries hand-written YAML after quoting special scalars and expanding leading tabs. */
+function frontmatterValue(yaml: string): Record<string, unknown> {
+	const object = (value: unknown): Record<string, unknown> =>
+		value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+	try { return object(parseYaml(yaml)); } catch { /* retry below */ }
+	const repaired = yaml.split("\n").map((line) => {
+		const match = line.match(/^([a-zA-Z_-]+):\s+(\S.*)$/);
+		if (!match) return line;
+		const [, key, value] = match;
+		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) return line;
+		if (value.startsWith("[") && value.endsWith("]")) {
+			try { if (Array.isArray(parseYaml(value))) return line; } catch { /* quote it below */ }
+		}
+		const escaped = value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+		return /[{}[\]*&#!|>%@`]|: /.test(value) ? `${key}: "${escaped}"` : line;
+	}).join("\n").replace(/^\t+/gm, (tabs) => "  ".repeat(tabs.length));
+	try { return object(parseYaml(repaired)); } catch { return {}; }
+}
+
+/** W1n/tgt/Sxe: remove frontmatter and block HTML comments, retain raw body whitespace. */
+export function parseRule(content: string): { content: string; globs?: string[] } {
+	const withoutBom = content.replace(/^\uFEFF/, "");
+	const match = withoutBom.match(/^---\s*\n([\s\S]*?)---\s*\n?/);
+	const metadata = match ? frontmatterValue(match[1]) : {};
+	let body = match ? withoutBom.slice(match[0].length) : content;
+	if (body.includes("<!--")) {
+		body = new Lexer({ gfm: false }).lex(body).map((token) => {
+			if (token.type !== "html" || !token.raw.trimStart().startsWith("<!--") || !token.raw.includes("-->")) return token.raw;
+			const residue = token.raw.replace(/<!--[\s\S]*?-->/g, "");
+			return residue.trim() ? residue : "";
+		}).join("");
+	}
+	const paths = splitRulePaths(metadata.paths).map((path) => path.endsWith("/**") ? path.slice(0, -3) : path).filter(Boolean);
+	return { content: body, ...(paths.length && !paths.every((path) => path === "**") ? { globs: paths } : {}) };
+}
+
+/** $ee/lje: ignore's gitignore semantics (including negation), never a glob-library approximation. */
+export function ruleMatches(globs: string[] | undefined, filePath: string, base: string): boolean {
+	if (!globs?.length) return false;
+	let candidate = isAbsolute(filePath) ? relative(base, filePath) : filePath;
+	if (isAbsolute(filePath) && !isRelativeInside(candidate)) {
+		// Both sides resolved: a cwd reached through a symlink (or a Windows 8.3
+		// short name) spells the base differently from the file's real directory.
+		const parent = tryRealpath(dirname(filePath));
+		if (parent) candidate = relative(tryRealpath(base) ?? base, join(parent, basename(filePath)));
+	}
+	if (!isRelativeInside(candidate)) return false;
+	return globMatcher(globs).ignores(forwardSlashes(candidate));
+}
+
+/** Compiled matchers by glob list: a read checks every conditional rule, so each list compiles once. */
+const matchers = new Map<string, Ignore>();
+
+function globMatcher(globs: string[]): Ignore {
+	const key = JSON.stringify(globs);
+	let matcher = matchers.get(key);
+	if (!matcher) {
+		const valid = globs.filter((glob) => {
+			try { ignore().add(glob).test("probe"); return true; } catch { return false; }
+		});
+		if (matchers.size >= 1024) matchers.clear();
+		matchers.set(key, (matcher = ignore().add(valid)));
+	}
+	return matcher;
+}
+
+/**
+ * The paths a walk being cached has looked at, each with its stat signature
+ * from before it was read: a change while the walk runs makes the next call
+ * walk again rather than keep what it read.
+ */
+let touched: Map<string, string> | undefined;
+
+function touch(path: string): void {
+	if (touched && !touched.has(path)) touched.set(path, signature(path));
+}
+
+/** What a stat can see of a path (through a link too); "-" when it is missing. */
+function signature(path: string): string {
+	try {
+		const link = lstatSync(path);
+		const stat = link.isSymbolicLink() ? statSync(path) : link;
+		return `${link.ino}:${stat.ino}:${stat.mtimeMs}:${stat.size}:${stat.nlink}`;
+	} catch {
+		return "-";
+	}
+}
+
+function isLink(path: string): boolean {
+	touch(path);
+	try { return lstatSync(path).isSymbolicLink(); } catch { return false; }
+}
+
+/**
+ * One Code addition, matching the inline expander (claude-context.ts
+ * `readImportTarget`): an import ending a sentence (`@docs/x.md.`) names
+ * `docs/x.md` when only that is a file. Claude Code reads the literal path,
+ * which wins whenever it exists.
+ */
+function withoutTrailingPunctuation(target: string): string {
+	for (let candidate = target; ; candidate = candidate.slice(0, -1)) {
+		touch(candidate);
+		try { if (statSync(candidate).isFile()) return candidate; } catch { /* not a file: peel */ }
+		if (candidate.length <= 1 || !/[.,;:!?)\]]$/.test(candidate)) return target;
+	}
+}
+
+/** Y1n: imports are separate instruction files, not substitutions into the rule's body. */
+function ruleImports(content: string, path: string, home: string): string[] {
+	const found = new Set<string>();
+	const text = (body: string) => {
+		for (const match of body.matchAll(/(?:^|\s)@((?:[^\s\\]|\\ )+)/g)) {
+			const ref = match[1].split("#")[0].replaceAll("\\ ", " ");
+			if (!ref || !(ref.startsWith("./") || ref.startsWith("~/") || (ref.startsWith("/") && ref !== "/") || /^[a-zA-Z0-9._-]/.test(ref))) continue;
+			found.add(withoutTrailingPunctuation(absoluteFrom(dirname(path), expandTilde(ref, home))));
+		}
+	};
+	const walk = (tokens: Token[]) => {
+		for (const token of tokens) {
+			if (token.type === "code" || token.type === "codespan") continue;
+			if (token.type === "html") {
+				if (token.raw.trimStart().startsWith("<!--") && token.raw.includes("-->")) text(token.raw.replace(/<!--[\s\S]*?-->/g, ""));
+				continue;
+			}
+			if (token.type === "text") text(token.text);
+			if ("tokens" in token && token.tokens) walk(token.tokens);
+			if ("items" in token) walk(token.items);
+		}
+	};
+	walk(new Lexer({ gfm: false }).lex(content));
+	return [...found];
+}
+
+const TEXT_EXTENSIONS = new Set([
+	".md", ".txt", ".text", ".json", ".yaml", ".yml", ".toml", ".xml", ".csv", ".html", ".htm", ".css", ".scss", ".sass", ".less",
+	".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".py", ".pyi", ".pyw", ".rb", ".erb", ".rake", ".go", ".rs",
+	".java", ".kt", ".kts", ".scala", ".c", ".cpp", ".cc", ".cxx", ".h", ".hpp", ".hxx", ".cs", ".swift", ".sh", ".bash", ".zsh",
+	".fish", ".ps1", ".bat", ".cmd", ".env", ".ini", ".cfg", ".conf", ".config", ".properties", ".sql", ".graphql", ".gql", ".proto",
+	".vue", ".svelte", ".astro", ".ejs", ".hbs", ".pug", ".jade", ".php", ".pl", ".pm", ".lua", ".r", ".dart", ".ex", ".exs",
+	".erl", ".hrl", ".clj", ".cljs", ".cljc", ".edn", ".hs", ".lhs", ".elm", ".ml", ".mli", ".f", ".f90", ".f95", ".for",
+	".cmake", ".make", ".makefile", ".gradle", ".sbt", ".rst", ".adoc", ".asciidoc", ".org", ".tex", ".latex", ".lock", ".log", ".diff", ".patch",
+]);
+
+export interface RuleOptions {
+	rulesDir: string;
+	cwd: string;
+	home: string;
+	scope: "Project" | "User" | "Managed";
+	/** Undefined selects unconditional files; a target selects only matching conditional files. */
+	filePath?: string;
+	/** Select every conditional file, whatever its globs (the auto-mode classifier's instructions). */
+	allConditional?: boolean;
+	processed?: Set<string>;
+	/** Normal CLI user rules allow external includes; project/managed rules need approval. */
+	includeExternal?: boolean;
+	/** Independent mode excludes Claude locations before reading or following their imports. */
+	allowPath?: (path: string) => boolean;
+	/**
+	 * The directory a project file belongs to (`<dir>` for `<dir>/.claude/CLAUDE.md`).
+	 * A file linked out of both it and the cwd is an external include, like an import.
+	 */
+	ownerDir?: string;
+}
+
+/** A text extension, or none: checked for the name read and, through a link, the file it points to. */
+function textExtension(path: string): boolean {
+	const ext = extname(path).toLowerCase();
+	return !ext || TEXT_EXTENSIONS.has(ext);
+}
+
+/** lJ: parent first, separate parsed imports, canonical dedupe, depths zero through four. */
+export function readRuleInstructions(path: string, opts: Pick<RuleOptions, "cwd" | "home" | "scope" | "processed" | "includeExternal" | "allowPath" | "ownerDir">): RuleFile[] {
+	const includeExternal = opts.includeExternal ?? opts.scope === "User";
+	const processed = opts.processed ?? new Set<string>();
+	const realCwd = tryRealpath(opts.cwd) ?? opts.cwd;
+	const inside = (target: string) => isPathAtOrUnder(target, realCwd);
+	const realOwner = opts.ownerDir === undefined ? undefined : tryRealpath(opts.ownerDir) ?? opts.ownerDir;
+	const load = (path: string, depth = 0, parent?: string): RuleFile[] => {
+		touch(path);
+		const key = tryRealpath(path);
+		if (key) touch(key);
+		if (!key || depth >= 5 || processed.has(comparablePath(key)) || (opts.allowPath && (!opts.allowPath(path) || !opts.allowPath(key))) || (depth > 0 && !includeExternal && !inside(key))) return [];
+		// One Code addition: a project file linked out of the project is an include the user must approve.
+		const linkedOut = depth === 0 && realOwner !== undefined && !inside(key) && !isPathAtOrUnder(key, realOwner);
+		if (linkedOut && !includeExternal) return [];
+		try {
+			const stat = statSync(key);
+			if (!stat.isFile() || stat.size > MAX_INSTRUCTION_BYTES || (opts.scope === "User" && !includeExternal && (stat.nlink > 1 || (depth === 0 && isLink(path))))) return [];
+			processed.add(comparablePath(key));
+			if (!textExtension(path) || !textExtension(key)) return [];
+			const parsed = parseRule(readFileSync(key, "utf8"));
+			if (!parsed.content.trim()) return [];
+			return [{ path, key, ...parsed, ...(parent ? { parent } : {}), ...(linkedOut ? { linkedFrom: path } : {}) }, ...ruleImports(parsed.content, key, opts.home).flatMap((ref) => load(ref, depth + 1, key))];
+		} catch { return []; }
+	};
+	return load(path);
+}
+
+/**
+ * Parsed walks by rules directory, scope, consent, cwd and home. Every `read`
+ * attaches rules, so a walk (readdir, realpath, read, lex and YAML per file) is
+ * reused while a stat of every path it looked at, imports and missing paths
+ * included, still matches. Consent is part of the key: a walk made without it
+ * is never served with it, or the other way round.
+ */
+const walks = new Map<string, { stamps: Map<string, string>; files: RuleFile[] }>();
+
+/** o$e: readdir order, depth-first, lowercase .md only; canonical identities stop link cycles. */
+export function discoverRules(opts: RuleOptions): RuleFile[] {
+	const base = opts.scope === "Project" ? dirname(dirname(opts.rulesDir)) : opts.cwd;
+	const select = (files: RuleFile[]) =>
+		files
+			.filter((file) => (opts.allConditional ? Boolean(file.globs) : opts.filePath === undefined ? !file.globs : ruleMatches(file.globs, opts.filePath, base)))
+			.map((file) => ({ ...file }));
+	// A shared dedupe set or a path filter makes the walk depend on its caller: never cached.
+	if (opts.processed || opts.allowPath || touched) return select(walkRules(opts));
+	const key = JSON.stringify([opts.rulesDir, opts.scope, opts.includeExternal ?? opts.scope === "User", opts.cwd, opts.home]);
+	const cached = walks.get(key);
+	if (cached && [...cached.stamps].every(([path, stamp]) => signature(path) === stamp)) return select(cached.files);
+	const stamps = new Map<string, string>();
+	touched = stamps;
+	let files: RuleFile[];
+	try { files = walkRules(opts); } finally { touched = undefined; }
+	if (walks.size >= 256) walks.clear();
+	walks.set(key, { stamps, files });
+	return select(files);
+}
+
+function walkRules(opts: RuleOptions): RuleFile[] {
+	const includeExternal = opts.includeExternal ?? opts.scope === "User";
+	const visited = new Set<string>();
+	const processed = opts.processed ?? new Set<string>();
+	const realCwd = tryRealpath(opts.cwd) ?? opts.cwd;
+	const inside = (path: string) => isPathAtOrUnder(path, realCwd);
+	const walk = (dir: string, linkedFrom?: string): RuleFile[] => {
+		touch(dir);
+		const real = tryRealpath(dir);
+		if (real) touch(real);
+		if (!real || visited.has(comparablePath(real))) return [];
+		// o2n/Tgt allow external user rules. o$e's J1n gate checks a linked
+		// .claude parent only on the cwd/ancestor walk, not on nested directories.
+		const linkedProjectParent = opts.scope === "Project" && isPathAtOrUnder(opts.cwd, dirname(dirname(dir))) && isLink(dirname(dir));
+		if (!includeExternal && !inside(real) && (isLink(dir) || linkedProjectParent)) return [];
+		visited.add(comparablePath(real));
+		const files: RuleFile[] = [];
+		try {
+			for (const entry of readdirSync(real, { withFileTypes: true })) {
+				const path = join(real, entry.name);
+				touch(path);
+				const key = tryRealpath(path);
+				if (!key || (!includeExternal && key !== path && !inside(key))) continue;
+				const stat = entry.isSymbolicLink() ? statSync(key) : entry;
+				const source = linkedFrom ? join(linkedFrom, entry.name) : join(dir, entry.name);
+				if (stat.isDirectory()) files.push(...walk(key, source !== key ? source : undefined));
+				else if (stat.isFile() && entry.name.endsWith(".md")) {
+					files.push(...readRuleInstructions(key, { ...opts, processed }).map((file) =>
+						file.key === key && source !== key ? { ...file, linkedFrom: source } : file,
+					));
+				}
+			}
+			return files;
+		} catch { return []; }
+	};
+	return walk(opts.rulesDir);
+}

package/extensions/lib/claude-settings.ts

@@ -12,8 +12,10 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { claudeUserDir } from "./paths.ts";
+import { join, posix, win32 } from "node:path";
+import { claudeSourcesOn, userConfigDir } from "./config-mode.ts";
+import { oneCodeProjectSettingsPath, oneCodeSettingsPath } from "./one-code-settings.ts";
+import { claudeManagedDir, claudeUserDir } from "./paths.ts";
 
 export interface ClaudeSettingsFile {
 	enabledPlugins?: Record<string, unknown>;
@@ -29,6 +31,75 @@ export function claudeUserSettingsPath(home: string): string {
 	return join(claudeUserDir(home), "settings.json");
 }
 
+/** Managed-settings locations, highest authority: `managed-settings.json` in Claude Code's managed root. */
+export function managedSettingsPaths(platform: NodeJS.Platform = process.platform): string[] {
+	const { join: joinFor } = platform === "win32" ? win32 : posix;
+	return [joinFor(claudeManagedDir(platform), "managed-settings.json")];
+}
+
+/** Claude Code's `instructionFiles` values (findings §57); the default is `claude-md-or-agents-md`. */
+export type InstructionFiles = "claude-md" | "claude-md-or-agents-md" | "claude-md-and-agents-md" | "managed-only";
+const INSTRUCTION_FILES: readonly InstructionFiles[] = ["claude-md", "claude-md-or-agents-md", "claude-md-and-agents-md", "managed-only"];
+const LEGACY_PROJECT_INSTRUCTIONS: Record<string, InstructionFiles> = {
+	none: "managed-only",
+	claude: "claude-md",
+	"agents-fallback": "claude-md-or-agents-md",
+	both: "claude-md-and-agents-md",
+};
+/** The AGENTS.md plugin's `pluginConfigs` keys: the id is inferred, so the bare name counts too. */
+const AGENTS_MD_PLUGIN_KEYS = ["cc-plugin-agents-md@builtin", "cc-plugin-agents-md"];
+
+/**
+ * Claude Code's `instructionFiles` (findings §57): the AGENTS.md plugin's option
+ * under `pluginConfigs[<id>].options`, from the user and managed settings
+ * (Claude Code reads no project file for it), managed winning. The legacy
+ * top-level `projectInstructions` applies only while `instructionFiles` is unset,
+ * mapped as Claude Code maps it (an unknown string reads as `claude-md`).
+ */
+export function readInstructionFiles(home: string): InstructionFiles {
+	let instructionFiles: InstructionFiles | undefined;
+	let legacy: InstructionFiles | undefined;
+	for (const path of [claudeUserSettingsPath(home), ...managedSettingsPaths()]) {
+		const file = readSettingsFile(path);
+		if (!file) continue;
+		const configs = file.pluginConfigs as Record<string, { options?: Record<string, unknown> }> | undefined;
+		for (const key of AGENTS_MD_PLUGIN_KEYS) {
+			const value = configs?.[key]?.options?.instructionFiles;
+			if (INSTRUCTION_FILES.includes(value as InstructionFiles)) instructionFiles = value as InstructionFiles;
+		}
+		if (typeof file.projectInstructions === "string") legacy = LEGACY_PROJECT_INSTRUCTIONS[file.projectInstructions] ?? "claude-md";
+	}
+	return instructionFiles ?? legacy ?? "claude-md-or-agents-md";
+}
+
+/** Where a settings file sits: Claude Code's ladder, One Code's two files, or managed policy. */
+export type SettingsSource = "claude-user" | "onecode-user" | "project" | "project-local" | "onecode-project" | "managed";
+
+/**
+ * Every settings file One Code reads Claude Code's keys from, lowest
+ * precedence first, with its source. Managed settings last: Claude Code's
+ * organisation policy outranks every user/project file (review P14).
+ * Independent mode (lib/config-mode.ts) reads One Code's own two files only,
+ * managed settings included in what it drops (decisions/memory-state.md).
+ * Each consumer keeps the sources its keys may come from.
+ */
+export function settingsSources(cwd: string, home: string): Array<[SettingsSource, string]> {
+	const oneCode: Array<[SettingsSource, string]> = [
+		["onecode-user", oneCodeSettingsPath(home)],
+		["onecode-project", oneCodeProjectSettingsPath(cwd, home)],
+	];
+	if (!claudeSourcesOn()) return oneCode;
+	const paths = settingsPaths(cwd, home);
+	return [
+		["claude-user", paths.user],
+		oneCode[0],
+		["project", paths.project],
+		["project-local", paths.local],
+		oneCode[1],
+		...managedSettingsPaths().map((path): [SettingsSource, string] => ["managed", path]),
+	];
+}
+
 export function settingsPaths(cwd: string, home: string): { user: string; project: string; local: string } {
 	return {
 		user: claudeUserSettingsPath(home),
@@ -56,7 +127,8 @@ export function readSettingsFile(path: string): ClaudeSettingsFile | undefined {
  * its project-trust prompt).
  */
 export function readSettingsEnv(home: string): Record<string, string> {
-	const env = readSettingsFile(claudeUserSettingsPath(home))?.env;
+	// The mode's user file: One Code's own in independent mode (lib/config-mode.ts).
+	const env = readSettingsFile(join(userConfigDir(home), "settings.json"))?.env;
 	if (!env || typeof env !== "object" || Array.isArray(env)) return {};
 	const out: Record<string, string> = {};
 	for (const [key, value] of Object.entries(env as Record<string, unknown>)) {
@@ -70,8 +142,8 @@ export function readSettingsEnv(home: string): Record<string, string> {
  * 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> = {};
+	const paths = settingsPaths(cwd, home);
 	for (const path of [paths.user, paths.project, paths.local]) {
 		const enabled = readSettingsFile(path)?.enabledPlugins;
 		if (!enabled || typeof enabled !== "object") continue;

package/extensions/lib/compaction-boundary.ts

@@ -0,0 +1,36 @@
+/**
+ * The latest compaction on a session branch, and where the entries still in
+ * context start. Pure: no pi imports; pi's `SessionEntry` fits the shape.
+ *
+ * pi builds the context after a compaction as the summary, then the kept
+ * entries from `firstKeptEntryId` (which lie before the compaction entry on the
+ * branch), then everything after the compaction (`buildContextEntries`). A
+ * first kept entry not found before the compaction keeps nothing.
+ */
+
+type BranchEntry = { id?: string; type?: string; timestamp?: string; firstKeptEntryId?: string | null };
+
+export interface CompactionBoundary {
+	/** Index of the latest compaction entry on the branch. */
+	index: number;
+	/** Index of its first kept entry, or `index` when it keeps nothing. */
+	keptStart: number;
+	/** The compaction's time in ms: every message produced since is newer, every kept one older. */
+	time: number;
+}
+
+/** The latest compaction on the branch, or undefined when there is none. */
+export function latestCompaction(entries: readonly unknown[]): CompactionBoundary | undefined {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index] as BranchEntry | undefined;
+		if (entry?.type !== "compaction") continue;
+		const kept = entries.findIndex((candidate) => (candidate as BranchEntry | undefined)?.id === entry.firstKeptEntryId);
+		return { index, keptStart: kept >= 0 && kept < index ? kept : index, time: Date.parse(entry.timestamp ?? "") };
+	}
+	return undefined;
+}
+
+/** The branch entries still in context: from the latest compaction's kept tail on, else all of them. */
+export function inContextEntries<E>(entries: readonly E[]): E[] {
+	return entries.slice(latestCompaction(entries)?.keptStart ?? 0);
+}

package/extensions/lib/compaction-keep.mjs

@@ -0,0 +1,83 @@
+/**
+ * pi's compaction keep window (`compaction.keepRecentTokens`), set to 0 for
+ * One Code.
+ *
+ * One Code's compaction keeps only the last assistant reply, as Claude Code
+ * does (`compaction/cut.ts`), so pi's window of recent tokens kept verbatim
+ * (20,000 by default) no longer decides what stays. It still decides whether
+ * a compaction can happen: pi's `prepareCompaction` gives up with "Nothing to
+ * compact (session too small)" when the whole session fits in the window,
+ * before any extension sees the request, so `/compact` on a short session
+ * failed. At 0, pi cuts at the last reply itself and any session with one
+ * finished turn compacts (findings §8).
+ *
+ * The bundled app writes 0 into its own settings unless the user set a value;
+ * on the user's own pi, One Code asks once (`branding/compaction-keep.ts`) and
+ * `/doctor` shows the setting.
+ *
+ * Plain JS with no pi imports, like replaced-builtins.mjs: app/bin.mjs loads it
+ * on bare Node before pi does.
+ */
+
+/** The keep window One Code wants. */
+export const ONE_CODE_KEEP_RECENT_TOKENS = 0;
+
+/** pi's default when no settings file sets one. */
+const PI_DEFAULT_KEEP_RECENT_TOKENS = 20000;
+
+/**
+ * Settings with the keep window set to One Code's when the user has not set
+ * one; `changed` says whether anything was written. An explicit value, pi's
+ * default included, is the user's and stays.
+ */
+export function withCompactionKeepBackfilled(settings) {
+	const compaction = settings?.compaction;
+	if (compaction !== undefined && (typeof compaction !== "object" || compaction === null || Array.isArray(compaction))) return { settings, changed: false };
+	if (compaction?.keepRecentTokens !== undefined) return { settings, changed: false };
+	return { settings: { ...settings, compaction: { ...compaction, keepRecentTokens: ONE_CODE_KEEP_RECENT_TOKENS } }, changed: true };
+}
+
+/**
+ * The keep window pi will use for `modelKey` (`provider/id`), and where it
+ * comes from, as pi resolves it: the model's `compaction.modelOverrides` entry
+ * first, then the ordinary setting; the project's settings win over the
+ * user's in each; `default` when nothing sets it. `model` names the override
+ * that supplied the value.
+ */
+export function compactionKeepView(userSettings, projectSettings, modelKey) {
+	// Set means defined, as for the backfill; pi itself rejects a non-integer.
+	const read = (value) => (value === undefined ? undefined : Number(value));
+	const scopes = [
+		["project", projectSettings],
+		["user", userSettings],
+	];
+	if (modelKey !== undefined) {
+		for (const [source, settings] of scopes) {
+			const value = read(settings?.compaction?.modelOverrides?.[modelKey]?.keepRecentTokens);
+			if (value !== undefined) return { value, source, model: modelKey };
+		}
+	}
+	for (const [source, settings] of scopes) {
+		const value = read(settings?.compaction?.keepRecentTokens);
+		if (value !== undefined) return { value, source };
+	}
+	return { value: PI_DEFAULT_KEEP_RECENT_TOKENS, source: "default" };
+}
+
+export const KEEP_YES = "Yes, set it to 0";
+export const KEEP_NO = "No, leave the setting";
+
+/** The startup question on the user's own pi. */
+export function keepWindowPrompt(settingsPath) {
+	return [
+		`One Code compacts like Claude Code: it keeps only the last reply after the summary.`,
+		`pi's compaction.keepRecentTokens (${PI_DEFAULT_KEEP_RECENT_TOKENS} by default) no longer changes what is kept; it only makes /compact refuse a session shorter than that.`,
+		`Set it to 0 in ${settingsPath}? It takes effect from the next start.`,
+	].join("\n");
+}
+
+/** The fix /doctor names for a keep window above 0, in the settings file (and model override) that sets it. */
+export function keepWindowFix(settingsPath, model) {
+	const key = model === undefined ? `"keepRecentTokens": 0` : `"modelOverrides": { "${model}": { "keepRecentTokens": 0 } }`;
+	return `Set "compaction": { ${key} } in ${settingsPath}, then restart.`;
+}