one-code-extension 0.4.1 → 0.6.0

package/extensions/lib/claude-context.ts

@@ -1,13 +1,14 @@
 /**
- * Claude Code's `# claudeMd` context block — the single `<system-reminder>` that
- * carries the CLAUDE.md files, the MEMORY.md index, the user's email, and the
- * date, prepended to the first user message (see extensions/claude-context for
- * the wiring, and lib/reminders.ts for placement).
+ * Claude Code's three first-message context reminders: the instructions block
+ * (the CLAUDE.md files and the MEMORY.md index), the context block (the user's
+ * email and the git snapshot) and the date, each its own `<system-reminder>`
+ * (see extensions/claude-context for the wiring, and lib/reminders.ts for
+ * placement; on a model that takes a mid-conversation system message the date
+ * moves into it, lib/system-role.ts).
  *
- * This module is pure (no pi imports) and byte-exact against real Claude Code
- * captures (opus-4-8.json / latest-haiku.json). The block is identical across
- * model tiers — only the `# Memory` *spec* in the system prompt varies by tier
- * (handled in lib/memory.ts), never this block.
+ * This module is pure (no pi imports) and byte-exact with Claude Code. The
+ * blocks are identical across model tiers — only the `# Memory` *spec* in the
+ * system prompt varies by tier (handled in lib/memory.ts), never these blocks.
  *
  * Discovery mirrors Claude Code, not pi's own loader: global `~/.claude/CLAUDE.md`
  * first, then project `CLAUDE.md` / `CLAUDE.local.md` from the farthest ancestor
@@ -26,24 +27,31 @@
  *     block so they take precedence over CLAUDE.md — keeping `# claudeMd` itself
  *     byte-exact with Claude Code.
  *
- * What is NOT yet replicated: enterprise-policy files and nested subtree
- * CLAUDE.md loaded on-demand when a file under them is read (a follow-up needing
- * file-tracker integration; absent from every turn-1 capture we have).
+ * Nested subtree instruction files come later, when a file under them is read
+ * (`nestedInstructionFiles`, attached by the claude-context extension). Rules
+ * parsing, recursive discovery and path matching live in claude-rules.ts.
  */
 
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { dirname, isAbsolute, join } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
+import { type InstructionFiles, readInstructionFiles } from "./claude-settings.ts";
+import { claudeSourcesOn } from "./config-mode.ts";
+import { findGitRoot } from "./git.ts";
 import { tryReadFile } from "./plugins.ts";
-import { absoluteFrom, expandTilde } from "./paths.ts";
+import { absoluteFrom, claudeManagedDir, claudeUserDir, expandTilde, isPathAtOrUnder, oneCodeStateDir, tryRealpath } from "./paths.ts";
+import { discoverRules, MAX_INSTRUCTION_BYTES, readRuleInstructions, type RuleFile, type RuleOptions } from "./claude-rules.ts";
 
-/** One CLAUDE.md-family file as it appears in the block. `content` is raw (untrimmed). */
+/** One instruction section. Legacy content stays raw; new parsed files carry CC's trimmed startup body. */
 export interface ContextFile {
 	path: string;
 	content: string;
 	descriptor: string;
+	/** Actual inline imports; parsed imports are separate sections and use [] to prevent raw @token inference. */
+	imported?: string[];
 }
 
 export const GLOBAL_DESCRIPTOR = "user's private global instructions for all projects";
+export const MANAGED_DESCRIPTOR = "organization-managed policy instructions";
 export const PROJECT_DESCRIPTOR = "project instructions, checked into the codebase";
 export const LOCAL_DESCRIPTOR = "user's private project instructions, not checked in";
 export const MEMORY_DESCRIPTOR = "user's auto-memory, persists across conversations";
@@ -58,18 +66,36 @@ const ONECODE_NAMES = ["ONECODE.md", "onecode.md", "One Code.md"] as const;
 const MAX_IMPORT_DEPTH = 5;
 
 const PREAMBLE =
-	"As you answer the user's questions, you can use the following context:\n" +
-	"# claudeMd\n" +
 	"Codebase and user instructions are shown below. Be sure to adhere to these instructions. " +
 	"IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.";
 
-const TRAILER =
-	"      IMPORTANT: this context may or may not be relevant to your tasks. " +
-	"You should not respond to this context unless it is highly relevant to your task.";
+const CONTEXT_PREAMBLE = "As you answer the user's questions, you can use the following context:";
+
+/** Claude Code's sentence after the email, with One Code named as the harness that attached it. */
+const EMAIL_USE =
+	"Use it only to identify the user, such as for authorship, attribution, or filtering their own work. " +
+	"Never send it to an unrelated service, such as in a request header, URL, or payload, unless the user explicitly asks.";
+
+const CONTEXT_FOOTER =
+	"One Code attached this context automatically; it isn't part of the user's message. " +
+	"It describes the user's own account and workspace, so they don't need it reported back.";
+
+/** Independent mode excludes Claude locations even when reached through aliases or imports. */
+export function isClaudeLocation(path: string, userDir: string): boolean {
+	return [path, tryRealpath(path)].some((candidate) => candidate !== undefined && (
+		/(?:^|[/\\])\.claude(?:[/\\]|$)/i.test(candidate) ||
+		/(?:^|[/\\])CLAUDE(?:\.local)?\.md$/i.test(candidate) ||
+		isPathAtOrUnder(candidate, tryRealpath(userDir) ?? userDir) ||
+		isPathAtOrUnder(candidate, claudeManagedDir())
+	));
+}
 
-function readFileIfPresent(path: string): string | null {
+/** A regular file within the instruction size limit (never a FIFO, which would block), else null. */
+export function readFileIfPresent(path: string): string | null {
 	try {
-		if (!existsSync(path) || !statSync(path).isFile()) return null;
+		if (!existsSync(path)) return null;
+		const stat = statSync(path);
+		if (!stat.isFile() || stat.size > MAX_INSTRUCTION_BYTES) return null;
 	} catch {
 		return null;
 	}
@@ -101,7 +127,7 @@ function isPresentFile(path: string): boolean {
  * costs a few stats and never lists the directory. Only when a probe hits do we
  * read the directory once to recover the real casing.
  */
-function firstOneCodeFile(dir: string): string | null {
+export function firstOneCodeFile(dir: string): string | null {
 	if (!ONECODE_NAMES.some((n) => isPresentFile(join(dir, n)))) return null;
 	let entries: string[];
 	try {
@@ -266,55 +292,128 @@ export function ancestorDirs(cwd: string): string[] {
 }
 
 /**
- * The ordered CLAUDE.md-family paths that exist, WITHOUT reading their contents:
- * global `~/.claude/CLAUDE.md` first, then project `CLAUDE.md`/`CLAUDE.local.md`
- * from the farthest ancestor down to cwd (`CLAUDE.md` before `CLAUDE.local.md`
- * within a directory). `discoverContextFiles` reads content on top of this;
- * callers that only need paths/descriptors (e.g. `/memory`'s picker) use it
- * directly to avoid loading files they will discard.
+ * Which instruction files load: Claude Code's `instructionFiles` values
+ * (findings §57) in Claude-compatible mode, or `agents-md` in independent mode
+ * (lib/config-mode.ts), where no CLAUDE.md-family file is read and every
+ * directory's `AGENTS.md` loads.
+ */
+export type InstructionRule = InstructionFiles | "agents-md";
+
+/** The rule One Code runs under: independent mode's own, else Claude Code's `instructionFiles`. */
+export function instructionRule(home: string): InstructionRule {
+	return claudeSourcesOn() ? readInstructionFiles(home) : "agents-md";
+}
+
+/**
+ * Whether `dir` holds a CLAUDE.md that puts Claude's instructions in play for
+ * `claude-md-or-agents-md`: CLAUDE.md, .claude/CLAUDE.md (never at the
+ * filesystem root) or CLAUDE.local.md.
+ */
+function dirHasClaudeMd(dir: string, present: (path: string) => boolean = isPresentFile): boolean {
+	return present(join(dir, "CLAUDE.md")) || (dirname(dir) !== dir && present(join(dir, ".claude", "CLAUDE.md"))) || present(join(dir, "CLAUDE.local.md"));
+}
+
+/**
+ * The ordered instruction-file paths that exist, WITHOUT reading their
+ * contents: global `~/.claude/CLAUDE.md` first, then per directory from the
+ * farthest ancestor down to cwd `CLAUDE.md`, the AGENTS.md files at its
+ * position, and `CLAUDE.local.md`. `discoverContextFiles` reads content on top
+ * of this; callers that only need paths/descriptors (e.g. `/memory`'s picker)
+ * use it directly to avoid loading files they will discard.
+ *
+ * `rule` (default `claude-md`) decides the AGENTS.md files, as Claude Code's
+ * `instructionFiles` does (findings §57): `claude-md-or-agents-md` loads every
+ * ancestor `AGENTS.md` and `.claude/AGENTS.md` only when the project has no
+ * `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` anywhere on that path (a per-project
+ * decision, so `# claudeMd` stays byte-exact with CC whenever CLAUDE.md is
+ * present); `claude-md-and-agents-md` loads them beside CLAUDE.md;
+ * `managed-only` drops the user's and the project's files, retaining managed
+ * instructions; `agents-md` reads only `AGENTS.md`, with no Claude Code
+ * file at all.
  *
  * When `homeOneCodeDir` is given, One Code's own `ONECODE.md` files join the
  * list: the global one from `~/.onecode` right after the global CLAUDE.md, and
- * each directory's after its CLAUDE.md/CLAUDE.local.md. The `/memory` picker passes
- * it (so ONECODE.md is an editable target); the model-facing `# claudeMd` block
- * does NOT — there ONECODE.md rides its own `# oneCodeMd` block via
- * `discoverOneCodeFiles` instead, so `# claudeMd` stays byte-exact with CC.
- *
- * When `agentsFallback` is set, a directory with no `CLAUDE.md` falls back to its
- * `AGENTS.md` (CLAUDE.md > AGENTS.md — the first-match Codex/opencode do, but
- * CLAUDE-preferred for our CC-compat audience). A directory that has a CLAUDE.md
- * ignores its AGENTS.md, so `# claudeMd` stays byte-exact with CC whenever
- * CLAUDE.md is present.
+ * each directory's last. The `/memory` picker passes it (so ONECODE.md is an
+ * editable target); the model-facing `# claudeMd` block does NOT — there
+ * ONECODE.md rides its own `# oneCodeMd` block via `discoverOneCodeFiles`
+ * instead, so `# claudeMd` stays byte-exact with CC.
  */
-export function discoverContextFilePaths(opts: {
+interface DiscoveryOptions {
 	cwd: string;
 	homeClaudeDir: string;
 	homeOneCodeDir?: string;
-	agentsFallback?: boolean;
-}): ContextFilePath[] {
-	const paths: ContextFilePath[] = [];
+	managedDir?: string;
+	rule?: InstructionRule;
+	/** User consent for this project's external instruction imports. Never sourced from project files. */
+	includeExternal?: boolean;
+}
+
+export function discoverContextFilePaths(opts: DiscoveryOptions): ContextFilePath[] {
+	return discoverInstructionEntries(opts);
+}
+
+interface InstructionEntry extends ContextFilePath {
+	ruleFile?: RuleFile;
+}
+
+function discoverInstructionEntries(
+	opts: DiscoveryOptions,
+	rules: (dir: string, scope: RuleOptions["scope"], descriptor: string) => InstructionEntry[] = () => [],
+): InstructionEntry[] {
+	const paths: InstructionEntry[] = [];
 	const seen = new Set<string>();
 	const includeOneCode = opts.homeOneCodeDir !== undefined;
-
-	/** Adds the path if present; returns whether it was added. */
-	const push = (path: string, descriptor: string): boolean => {
-		if (seen.has(path) || !isPresentFile(path)) return false;
+	const rule = opts.rule ?? "claude-md";
+	const claudeFiles = rule !== "agents-md" && rule !== "managed-only";
+	const dirs = ancestorDirs(opts.cwd);
+	// Each path is checked once per call: the per-project test and the walk share it.
+	const presence = new Map<string, boolean>();
+	const present = (path: string): boolean => {
+		let found = presence.get(path);
+		if (found === undefined) presence.set(path, (found = isPresentFile(path)));
+		return found;
+	};
+	const projectHasClaude = () => dirs.some((d) => dirHasClaudeMd(d, present));
+	const agentsFiles =
+		rule === "agents-md" || rule === "claude-md-and-agents-md" || (rule === "claude-md-or-agents-md" && !projectHasClaude());
+
+	/** Adds the path if present. */
+	const push = (path: string, descriptor: string): void => {
+		if (!present(path) || (rule === "agents-md" && isClaudeLocation(path, opts.homeClaudeDir))) return;
+		const key = tryRealpath(path) ?? path;
+		if (seen.has(key)) return;
 		paths.push({ path, descriptor });
-		seen.add(path);
-		return true;
+		seen.add(key);
 	};
 
-	push(join(opts.homeClaudeDir, "CLAUDE.md"), GLOBAL_DESCRIPTOR);
+	if (rule !== "agents-md") {
+		const managed = opts.managedDir ?? claudeManagedDir();
+		push(join(managed, "CLAUDE.md"), MANAGED_DESCRIPTOR);
+		paths.push(...rules(join(managed, ".claude", "rules"), "Managed", MANAGED_DESCRIPTOR));
+	}
+	if (claudeFiles) {
+		push(join(opts.homeClaudeDir, "CLAUDE.md"), GLOBAL_DESCRIPTOR);
+		paths.push(...rules(join(opts.homeClaudeDir, "rules"), "User", GLOBAL_DESCRIPTOR));
+	}
 	if (includeOneCode && opts.homeOneCodeDir) {
 		const globalOneCode = firstOneCodeFile(opts.homeOneCodeDir);
 		if (globalOneCode) push(globalOneCode, ONECODE_GLOBAL_DESCRIPTOR);
 	}
 
-	for (const d of ancestorDirs(opts.cwd)) {
-		const hasClaude = push(join(d, "CLAUDE.md"), PROJECT_DESCRIPTOR);
-		// AGENTS.md stands in for a missing CLAUDE.md in this directory.
-		if (!hasClaude && opts.agentsFallback) push(join(d, "AGENTS.md"), AGENTS_DESCRIPTOR);
-		push(join(d, "CLAUDE.local.md"), LOCAL_DESCRIPTOR);
+	for (const d of dirs) {
+		if (claudeFiles) {
+			push(join(d, "CLAUDE.md"), PROJECT_DESCRIPTOR);
+			if (dirname(d) !== d) push(join(d, ".claude", "CLAUDE.md"), PROJECT_DESCRIPTOR);
+		}
+		if (agentsFiles) {
+			push(join(d, "AGENTS.md"), AGENTS_DESCRIPTOR);
+			// `.claude/AGENTS.md` is a Claude Code location; independent mode reads none.
+			if (claudeFiles) push(join(d, ".claude", "AGENTS.md"), AGENTS_DESCRIPTOR);
+		}
+		if (claudeFiles) {
+			if (dirname(d) !== d) paths.push(...rules(join(d, ".claude", "rules"), "Project", PROJECT_DESCRIPTOR));
+			push(join(d, "CLAUDE.local.md"), LOCAL_DESCRIPTOR);
+		}
 		if (includeOneCode) {
 			const oneCode = firstOneCodeFile(d);
 			if (oneCode) push(oneCode, ONECODE_DESCRIPTOR);
@@ -324,25 +423,269 @@ export function discoverContextFilePaths(opts: {
 	return paths;
 }
 
-export function discoverContextFiles(opts: {
+/**
+ * The project's own instruction files in play under the running rule
+ * (`instructionRule`), from cwd up to the git root (or just cwd outside a
+ * repo), nearest directory first; with `homeOneCodeDir`, its ONECODE.md files
+ * too. The startup banner lists these.
+ */
+export function projectInstructionFiles(opts: { cwd: string; home: string; homeOneCodeDir?: string }): string[] {
+	const stop = findGitRoot(opts.cwd) ?? opts.cwd;
+	const files = discoverContextFilePaths({ cwd: opts.cwd, homeClaudeDir: claudeUserDir(opts.home), homeOneCodeDir: opts.homeOneCodeDir, rule: instructionRule(opts.home) });
+	// The directory a file belongs to: `.claude/AGENTS.md` counts as its parent's.
+	const owner = (path: string) => (basename(dirname(path)) === ".claude" ? dirname(dirname(path)) : dirname(path));
+	return files
+		.filter(({ path, descriptor }) => descriptor !== GLOBAL_DESCRIPTOR && descriptor !== ONECODE_GLOBAL_DESCRIPTOR && isPathAtOrUnder(path, stop))
+		.map(({ path }) => path)
+		.sort((a, b) => owner(b).length - owner(a).length);
+}
+
+/**
+ * The instruction files Claude Code attaches when the model reads a file below
+ * the working directory (its `nested_memory` attachment): for each directory
+ * from just below cwd down to the file's own, `CLAUDE.md`, `.claude/CLAUDE.md`
+ * and `CLAUDE.local.md`, under the same rule as the startup block (AGENTS.md
+ * per `rule`, decided for the whole project as at startup; none of the
+ * CLAUDE.md family and no `.claude` directory in independent mode), plus One
+ * Code's ONECODE.md. Directories at or above cwd are left out: the startup
+ * block already carries them. Rules attach in Claude Code's order: managed/user
+ * conditional, nested files/rules, then ancestor conditional rules.
+ *
+ * Named nested files retain One Code's real-path confinement to the project;
+ * rules use claude-rules.ts's source-specific link/include policy. A symlink
+ * and its target are one file (`key`), and the file being read is never its
+ * own attachment. `imported` lists the real paths the legacy inline expander
+ * pulled in, so the caller can treat them as shown; parsed imports instead
+ * appear as their own files.
+ */
+export function nestedInstructionFiles(opts: {
+	filePath: string;
 	cwd: string;
-	homeClaudeDir: string;
-	homeOneCodeDir?: string;
-	agentsFallback?: boolean;
+	rule: InstructionRule;
+	home: string;
+	homeClaudeDir?: string;
+	managedDir?: string;
+	includeExternal?: boolean;
+}): { path: string; key: string; content: string; imported: string[] }[] {
+	const target = absoluteFrom(opts.cwd, opts.filePath);
+	if (target === absoluteFrom(opts.cwd, ".")) return [];
+	const realCwd = tryRealpath(opts.cwd) ?? opts.cwd;
+	const inProject = (path: string | undefined): path is string => path !== undefined && isPathAtOrUnder(path, realCwd);
+	// Named nested files stay confined to the project. An authorized read of a
+	// sibling can still match an ancestor's rule, whose base is that ancestor.
+	const realParent = tryRealpath(dirname(target));
+	let nestedParent = dirname(target);
+	if (!isPathAtOrUnder(nestedParent, opts.cwd) && inProject(realParent)) nestedParent = join(opts.cwd, relative(realCwd, realParent));
+	const walkNested = isPathAtOrUnder(nestedParent, opts.cwd) && inProject(realParent);
+	const realTarget = tryRealpath(target);
+	const claudeFiles = opts.rule !== "agents-md" && opts.rule !== "managed-only";
+	const dirs: string[] = [];
+	for (let dir = nestedParent; walkNested && isPathAtOrUnder(dir, opts.cwd) && !isPathAtOrUnder(opts.cwd, dir); dir = dirname(dir)) {
+		dirs.unshift(dir);
+		if (dirname(dir) === dir) break;
+	}
+	// Independent mode reads no Claude Code location, so it never walks into a `.claude` directory.
+	const userDir = opts.homeClaudeDir ?? claudeUserDir(opts.home);
+	const allowedLocation = (path: string) => opts.rule !== "agents-md" || !isClaudeLocation(path, userDir);
+	const walked = dirs.filter(allowedLocation);
+	// claude-md-or-agents-md is decided per project, as at startup: AGENTS.md only where no CLAUDE.md is in play.
+	const projectHasClaude = () =>
+		[...ancestorDirs(opts.cwd), ...walked].some((dir) => dirHasClaudeMd(dir));
+	const agents = opts.rule === "agents-md" || opts.rule === "claude-md-and-agents-md" || (opts.rule === "claude-md-or-agents-md" && !projectHasClaude());
+	// Approved external chains use the reference parser below; the legacy fallback stays confined.
+	const readAllowed = (path: string) => (allowedLocation(path) ? readFileIfPresent(path) : null);
+	const readInProject = (path: string) => (inProject(tryRealpath(path)) ? readAllowed(path) : null);
+	const seen = new Set<string>(realTarget ? [realTarget] : []);
+	const files: { path: string; key: string; content: string; imported: string[] }[] = [];
+	const addRules = (rulesDir: string, scope: RuleOptions["scope"], conditional: boolean) => {
+		for (const file of discoverRules({ rulesDir, scope, cwd: opts.cwd, home: opts.home, ...(scope !== "User" ? { includeExternal: opts.includeExternal } : {}), ...(conditional ? { filePath: target } : {}) })) {
+			if (seen.has(file.key)) continue;
+			seen.add(file.key);
+			files.push({ ...file, imported: [] });
+		}
+	};
+	if (opts.rule !== "agents-md") addRules(join(opts.managedDir ?? claudeManagedDir(), ".claude", "rules"), "Managed", true);
+	if (claudeFiles) addRules(join(opts.homeClaudeDir ?? claudeUserDir(opts.home), "rules"), "User", true);
+	for (const dir of walked) {
+		const candidates: string[] = [];
+		if (claudeFiles) candidates.push(join(dir, "CLAUDE.md"), join(dir, ".claude", "CLAUDE.md"));
+		if (agents) {
+			candidates.push(join(dir, "AGENTS.md"));
+			if (claudeFiles) candidates.push(join(dir, ".claude", "AGENTS.md"));
+		}
+		if (claudeFiles) candidates.push(join(dir, "CLAUDE.local.md"));
+		const oneCode = firstOneCodeFile(dir);
+		if (oneCode) candidates.push(oneCode);
+		for (const path of candidates) {
+			const key = tryRealpath(path);
+			if (!inProject(key) || seen.has(key) || !allowedLocation(path)) continue;
+			if (basename(dirname(path)) === ".claude" && basename(path) === "CLAUDE.md") {
+				for (const file of readRuleInstructions(path, { cwd: opts.cwd, home: opts.home, scope: "Project", includeExternal: opts.includeExternal })) {
+					if (seen.has(file.key)) continue;
+					seen.add(file.key);
+					files.push({ ...file, imported: [] });
+				}
+				continue;
+			}
+			const external = path !== oneCode ? approvedExternalInstructions(path, opts) : undefined;
+			if (external) {
+				for (const file of external) {
+					if (seen.has(file.key)) continue;
+					seen.add(file.key);
+					files.push({ ...file, imported: [] });
+				}
+				continue;
+			}
+			const content = readFileIfPresent(path);
+			if (content === null || content.trim() === "") continue;
+			seen.add(key);
+			// ONECODE.md keeps its inline expander; approval lifts the confinement, as at startup.
+			const read = path === oneCode && opts.includeExternal ? readAllowed : readInProject;
+			const imported = [...collectImportedPaths(content, dirname(path), { home: opts.home, read })].map((p) => tryRealpath(p) ?? p);
+			for (const p of imported) seen.add(p);
+			files.push({ path, key, content: expandImports(content, dirname(path), { home: opts.home, read }), imported });
+		}
+		if (claudeFiles) {
+			addRules(join(dir, ".claude", "rules"), "Project", false);
+			addRules(join(dir, ".claude", "rules"), "Project", true);
+		}
+	}
+	if (claudeFiles) for (const dir of ancestorDirs(opts.cwd)) if (dirname(dir) !== dir) addRules(join(dir, ".claude", "rules"), "Project", true);
+	return files;
+}
+
+/** Claude Code's `nested_memory` rendering (the reminder queue adds the `<system-reminder>` frame). */
+export function nestedInstructionText(file: { path: string; content: string }): string {
+	return `Contents of ${file.path}:\n\n${file.content}`;
+}
+
+export function discoverContextFiles(opts: DiscoveryOptions & {
 	/** Home directory for resolving `~` in `@path` imports. */
 	home: string;
 }): ContextFile[] {
 	const files: ContextFile[] = [];
-	for (const { path, descriptor } of discoverContextFilePaths(opts)) {
+	// Under claude-md-and-agents-md an AGENTS.md that a loaded file already
+	// imports, or whose content one already carries, is not loaded twice (CC).
+	const dedupe = opts.rule === "claude-md-and-agents-md";
+	const imported = new Set<string>();
+	const contents = new Set<string>();
+	const emitted = new Set<string>();
+	const parsedShown = new Set<string>();
+	const realCwd = tryRealpath(opts.cwd) ?? opts.cwd;
+	const readAllowedImport = (path: string) => opts.rule !== "agents-md" || !isClaudeLocation(path, opts.homeClaudeDir) ? readFileIfPresent(path) : null;
+	const readProjectImport = (path: string) => {
+		const key = tryRealpath(path);
+		return key && isPathAtOrUnder(key, realCwd) ? readAllowedImport(path) : null;
+	};
+	const appendParsed = (file: RuleFile, descriptor: string) => {
+		if (emitted.has(file.key)) return;
+		emitted.add(file.key);
+		parsedShown.add(file.key);
+		imported.add(file.key);
+		contents.add(file.content.trim());
+		files.push({ path: file.path, descriptor, content: file.content.trim(), imported: [] });
+	};
+	const entries = discoverInstructionEntries(opts, (rulesDir, scope, descriptor) =>
+		discoverRules({ rulesDir, scope, cwd: opts.cwd, home: opts.home, ...(scope !== "User" ? { includeExternal: opts.includeExternal } : {}) }).map((ruleFile) => ({ path: ruleFile.path, descriptor, ruleFile })),
+	);
+	for (const { path, descriptor, ruleFile } of entries) {
+		const key = tryRealpath(path) ?? path;
+		if (ruleFile) {
+			appendParsed(ruleFile, descriptor);
+			continue;
+		}
+		// ~/.claude/CLAUDE.md is the pre-existing global surface, not the new
+		// project location: leave its legacy bytes alone when no new files exist.
+		const dotClaude = descriptor === PROJECT_DESCRIPTOR && basename(dirname(path)) === ".claude" && basename(path) === "CLAUDE.md";
+		if (dotClaude || descriptor === MANAGED_DESCRIPTOR) {
+			for (const file of readRuleInstructions(path, { cwd: opts.cwd, home: opts.home, scope: descriptor === MANAGED_DESCRIPTOR ? "Managed" : "Project", includeExternal: opts.includeExternal, ...(dotClaude ? { ownerDir: dirname(dirname(path)) } : {}) })) appendParsed(file, descriptor);
+			continue;
+		}
+		if (parsedShown.has(key)) continue;
 		// Re-check the read: a file present at enumeration but unreadable now is
 		// omitted, exactly as before (the block must never carry empty entries).
 		const content = readFileIfPresent(path);
 		if (content === null) continue;
-		files.push({ path, content: expandImports(content, dirname(path), { home: opts.home }), descriptor });
+		if (dedupe) {
+			const trimmed = content.trim();
+			// Compared by real path, so a `./`-spelled or symlinked import still matches.
+			if (descriptor === AGENTS_DESCRIPTOR && (imported.has(tryRealpath(path) ?? path) || (trimmed !== "" && contents.has(trimmed)))) continue;
+			contents.add(trimmed);
+		}
+		// Keep legacy bytes when no external import exists. Approved external
+		// chains use the same parser as the warning probe (escaped spaces,
+		// fragments, depth/extension limits and separate imported sections).
+		const projectSource = descriptor === PROJECT_DESCRIPTOR || descriptor === LOCAL_DESCRIPTOR || descriptor === AGENTS_DESCRIPTOR;
+		const external = projectSource ? approvedExternalInstructions(path, opts) : undefined;
+		if (external) {
+			for (const file of external) appendParsed(file, descriptor);
+			continue;
+		}
+		const importOptions = { home: opts.home, read: projectSource ? readProjectImport : readAllowedImport };
+		const included = [...collectImportedPaths(content, dirname(path), importOptions)];
+		for (const p of included) {
+			const importedKey = tryRealpath(p) ?? p;
+			imported.add(importedKey);
+			emitted.add(importedKey);
+		}
+		files.push({ path, content: expandImports(content, dirname(path), importOptions), descriptor, ...(content.includes("@") ? { imported: included } : {}) });
+		emitted.add(key);
 	}
 	return files;
 }
 
+/** Use CC's parsed records for an approved external chain, without changing legacy no-import bytes. */
+function approvedExternalInstructions(path: string, opts: { cwd: string; home: string; homeClaudeDir?: string; rule?: InstructionRule; includeExternal?: boolean }): RuleFile[] | undefined {
+	if (!opts.includeExternal) return;
+	const files = readRuleInstructions(path, { cwd: opts.cwd, home: opts.home, scope: "Project", includeExternal: true,
+		allowPath: (path) => opts.rule !== "agents-md" || !isClaudeLocation(path, opts.homeClaudeDir ?? claudeUserDir(opts.home)),
+	});
+	const cwd = tryRealpath(opts.cwd) ?? opts.cwd;
+	return files.some((file) => file.parent && !isPathAtOrUnder(file.key, cwd)) ? files : undefined;
+}
+
+/**
+ * The startup warning probe: load with external includes enabled, then keep
+ * non-user imports/links outside cwd. Missing, empty, binary-extension and
+ * over-depth targets never become records, so they cannot cause a question.
+ * This scan is UI-only; its contents must never enter the reminder queue.
+ */
+export function externalInstructionIncludes(opts: DiscoveryOptions & { home: string }): string[] {
+	const outside: string[] = [];
+	const seen = new Set<string>();
+	const cwd = tryRealpath(opts.cwd) ?? opts.cwd;
+	const add = (file: RuleFile) => {
+		if ((!file.parent && !file.linkedFrom) || isPathAtOrUnder(file.key, cwd) || seen.has(file.key)) return;
+		seen.add(file.key);
+		outside.push(file.key);
+	};
+	const entries = discoverInstructionEntries(opts, (rulesDir, scope, descriptor) => {
+		if (scope === "User") return [];
+		return discoverRules({ rulesDir, scope, cwd: opts.cwd, home: opts.home, includeExternal: true })
+			.map((ruleFile) => ({ path: ruleFile.path, descriptor, ruleFile }));
+	});
+	for (const { path, descriptor, ruleFile } of entries) {
+		if (descriptor === GLOBAL_DESCRIPTOR || descriptor === ONECODE_GLOBAL_DESCRIPTOR || descriptor === ONECODE_DESCRIPTOR) continue;
+		if (ruleFile) { add(ruleFile); continue; }
+		const dotClaude = descriptor === PROJECT_DESCRIPTOR && basename(dirname(path)) === ".claude" && basename(path) === "CLAUDE.md";
+		for (const file of readRuleInstructions(path, { cwd: opts.cwd, home: opts.home, scope: descriptor === MANAGED_DESCRIPTOR ? "Managed" : "Project", includeExternal: true,
+			allowPath: (path) => opts.rule !== "agents-md" || !isClaudeLocation(path, opts.homeClaudeDir),
+			...(dotClaude ? { ownerDir: dirname(dirname(path)) } : {}),
+		})) add(file);
+	}
+	// A project ONECODE.md's imports, resolved by the expander that would load them.
+	for (const source of oneCodeSources({ cwd: opts.cwd, home: opts.home, homeOneCodeDir: opts.homeOneCodeDir ?? oneCodeStateDir(process.env, opts.home) })) {
+		if (source.descriptor !== ONECODE_DESCRIPTOR) continue;
+		for (const imported of collectImportedPaths(source.content, dirname(source.path), { home: opts.home, read: source.unconfined })) {
+			const key = tryRealpath(imported) ?? imported;
+			if (isPathAtOrUnder(key, cwd) || seen.has(key)) continue;
+			seen.add(key);
+			outside.push(key);
+		}
+	}
+	return outside;
+}
+
 /**
  * The ONECODE.md files that exist, ordered global-first then farthest ancestor
  * down to cwd (nearer wins). These ride in their own `# oneCodeMd` block, not the
@@ -352,31 +695,66 @@ function discoverOneCodeFilePaths(opts: { cwd: string; homeOneCodeDir: string })
 	const paths: ContextFilePath[] = [];
 	const seen = new Set<string>();
 	const push = (path: string | null, descriptor: string) => {
-		if (!path || seen.has(path)) return;
+		if (!path) return;
+		const key = tryRealpath(path) ?? path;
+		if (seen.has(key)) return;
 		paths.push({ path, descriptor });
-		seen.add(path);
+		seen.add(key);
 	};
 	push(firstOneCodeFile(opts.homeOneCodeDir), ONECODE_GLOBAL_DESCRIPTOR);
 	for (const d of ancestorDirs(opts.cwd)) push(firstOneCodeFile(d), ONECODE_DESCRIPTOR);
 	return paths;
 }
 
-/** ONECODE.md files with `@import`s expanded, for the `# oneCodeMd` block. */
-export function discoverOneCodeFiles(opts: { cwd: string; homeOneCodeDir: string; home: string }): ContextFile[] {
-	const files: ContextFile[] = [];
-	for (const { path, descriptor } of discoverOneCodeFilePaths(opts)) {
-		const content = readFileIfPresent(path);
-		if (content === null) continue;
-		files.push({ path, content: expandImports(content, dirname(path), { home: opts.home }), descriptor });
-	}
-	return files;
+/**
+ * The ONECODE.md files present, each with the readers for its `@import`s:
+ * `confined` is what loads without consent (anywhere for the user's global
+ * file, which the user wrote; at or under the cwd's real path for a project
+ * file, like CLAUDE.md), `unconfined` what loads once the user approved.
+ */
+function oneCodeSources(opts: { cwd: string; homeOneCodeDir: string; home: string }): {
+	path: string;
+	descriptor: string;
+	content: string;
+	confined: (path: string) => string | null;
+	unconfined: (path: string) => string | null;
+}[] {
+	const allowedLocation = (path: string) => claudeSourcesOn() || !isClaudeLocation(path, claudeUserDir(opts.home));
+	const unconfined = (path: string) => allowedLocation(path) ? readFileIfPresent(path) : null;
+	const realCwd = tryRealpath(opts.cwd) ?? opts.cwd;
+	const inProject = (path: string) => {
+		const key = tryRealpath(path);
+		return key && isPathAtOrUnder(key, realCwd) ? unconfined(path) : null;
+	};
+	return discoverOneCodeFilePaths(opts).flatMap(({ path, descriptor }) => {
+		const content = unconfined(path);
+		return content === null ? [] : [{ path, descriptor, content, unconfined, confined: descriptor === ONECODE_DESCRIPTOR ? inProject : unconfined }];
+	});
 }
 
-const ONECODE_PREAMBLE =
-	"# oneCodeMd\n" +
-	"The following are One Code-specific instructions, read only by One Code and not by other tools. " +
-	"IMPORTANT: they take precedence over the CLAUDE.md instructions above and over any default behavior — " +
-	"where they conflict with CLAUDE.md, follow these. Follow them exactly as written.";
+/**
+ * ONECODE.md files with `@import`s expanded, for the `# oneCodeMd` block. A
+ * project file's imports outside the cwd load only with `includeExternal`
+ * (the user's consent, as for CLAUDE.md), which `externalInstructionIncludes` asks for.
+ */
+export function discoverOneCodeFiles(opts: { cwd: string; homeOneCodeDir: string; home: string; includeExternal?: boolean }): ContextFile[] {
+	return oneCodeSources(opts).map(({ path, descriptor, content, confined, unconfined }) => {
+		const importOptions = { home: opts.home, read: opts.includeExternal ? unconfined : confined };
+		const imported = [...collectImportedPaths(content, dirname(path), importOptions)];
+		return { path, content: expandImports(content, dirname(path), importOptions), descriptor, ...(content.includes("@") ? { imported } : {}) };
+	});
+}
+
+/** The block's preamble, naming the files above it: AGENTS.md in independent mode (lib/config-mode.ts). */
+function oneCodePreamble(): string {
+	const above = claudeSourcesOn() ? "CLAUDE.md" : "AGENTS.md";
+	return (
+		"# oneCodeMd\n" +
+		"The following are One Code-specific instructions, read only by One Code and not by other tools. " +
+		`IMPORTANT: they take precedence over the ${above} instructions above and over any default behavior — ` +
+		`where they conflict with ${above}, follow these. Follow them exactly as written.`
+	);
+}
 
 /**
  * Assemble the `# oneCodeMd` block's inner text (wrapper added by lib/reminders.ts):
@@ -386,35 +764,62 @@ const ONECODE_PREAMBLE =
  */
 export function buildOneCodeBlock(files: ContextFile[]): string | null {
 	if (files.length === 0) return null;
-	const sections = files.map((s) => `Contents of ${s.path} (${s.descriptor}):\n\n${s.content}`).join("\n");
-	return `${ONECODE_PREAMBLE}\n\n${sections}`;
+	return withoutFinalNewline(`${oneCodePreamble()}\n\n${files.map(section).join("\n")}`);
 }
 
 export const AGENTS_DESCRIPTOR = "cross-tool agent instructions, AGENTS.md standard";
 
 /**
- * Assemble the block's inner text (the `<system-reminder>` wrapper is added by
- * lib/reminders.ts). Byte-exact rule reverse-engineered from opus-4-8.json:
+ * One file's section. Its content is raw, but always ends in a newline: the
+ * join rule relies on it, and a file without one would glue the next section,
+ * or the next section's header, onto its last line.
+ */
+function section(file: ContextFile): string {
+	const content = file.content.endsWith("\n") ? file.content : `${file.content}\n`;
+	return `Contents of ${file.path} (${file.descriptor}):\n\n${content}`;
+}
+
+/**
+ * The date reminder's value: the user's LOCAL calendar date as YYYY-MM-DD, the
+ * date their own clock shows (a UTC date is a day off every evening west of
+ * UTC and every early morning east of it).
+ */
+export function localDate(now: Date = new Date()): string {
+	const pad = (n: number) => String(n).padStart(2, "0");
+	return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
+/**
+ * Claude Code's notice when the local date moves on mid-session. The block
+ * carrying the date is frozen after the first request, so the new date
+ * rides a one-shot where the model reads next, the way Claude Code does.
+ */
+export function dateChangeReminder(date: string): string {
+	return `The date has changed. Today's date is now ${date}. No need to announce the new date \u2014 the user's own clock shows it.`;
+}
+
+/** The text without one trailing newline: the reminder frame supplies the newline before its closing tag. */
+function withoutFinalNewline(text: string): string {
+	return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+
+/**
+ * The instructions block's inner text (the `<system-reminder>` wrapper is added
+ * by lib/reminders.ts):
  *
  *   {PREAMBLE}\n\n
- *   {section}\n{section}\n…            ← sections joined by a single "\n"
- *   # userEmail\nThe user's email address is {email}.\n
- *   # currentDate\nToday's date is {date}.\n
- *   \n{TRAILER}
+ *   {section}\n{section}\n…{last section without its final newline}
  *
  * where each section is `Contents of {path} ({descriptor}):\n\n{content}` and
  * `content` keeps its own trailing newline (files are read raw, never trimmed —
- * a file ending in "\n" plus the join "\n" is the "\n\n" seen between sections;
- * the last section's own trailing "\n" is the single "\n" before `# userEmail`).
- *
- * `memoryIndex`, when present, is appended as a final context section with the
- * memory descriptor. Returns null when there is nothing at all to inject.
+ * a file ending in "\n" plus the join "\n" is the "\n\n" seen between
+ * sections). A file that does not end in "\n" gets one, so no header lands on
+ * its last line. `memoryIndex`, when present, is appended as a final section
+ * with the memory descriptor. Returns null when there is nothing to inject.
  */
 export function buildClaudeMdBlock(opts: {
 	contextFiles: ContextFile[];
 	memoryIndex?: { path: string; content: string } | null;
-	email?: string | null;
-	date: string;
 }): string | null {
 	const sections = [...opts.contextFiles];
 	if (opts.memoryIndex && opts.memoryIndex.content.trim()) {
@@ -424,15 +829,25 @@ export function buildClaudeMdBlock(opts: {
 			descriptor: MEMORY_DESCRIPTOR,
 		});
 	}
+	if (sections.length === 0) return null;
+	return withoutFinalNewline(`${PREAMBLE}\n\n${sections.map(section).join("\n")}`);
+}
 
-	if (sections.length === 0 && !opts.email) return null;
+/**
+ * The context block's inner text: the preamble, `# userEmail` with Claude
+ * Code's use-only-to-identify sentence, the `# gitStatus` snapshot
+ * (lib/git-status.ts), then a blank line and the footer. Null with neither an
+ * email nor a snapshot.
+ */
+export function buildContextBlock(opts: { email?: string | null; gitStatus?: string | null }): string | null {
+	const parts: string[] = [];
+	if (opts.email) parts.push(`# userEmail\nThe user's email address is ${opts.email}. ${EMAIL_USE}`);
+	if (opts.gitStatus) parts.push(opts.gitStatus);
+	if (parts.length === 0) return null;
+	return `${CONTEXT_PREAMBLE}\n${parts.join("\n")}\n\n${CONTEXT_FOOTER}`;
+}
 
-	let inner = `${PREAMBLE}\n\n`;
-	inner += sections.map((s) => `Contents of ${s.path} (${s.descriptor}):\n\n${s.content}`).join("\n");
-	if (opts.email) {
-		inner += `# userEmail\nThe user's email address is ${opts.email}.\n`;
-	}
-	inner += `# currentDate\nToday's date is ${opts.date}.\n`;
-	inner += `\n${TRAILER}`;
-	return inner;
+/** The date reminder's inner text, sent whether or not any CLAUDE.md exists. */
+export function dateBlock(date: string): string {
+	return `Today's date is ${date}.`;
 }