one-code-extension 0.1.0

package/extensions/hooks/protocol.ts

@@ -0,0 +1,151 @@
+/**
+ * Claude Code hook protocol (pure): the stdin payload shape, the stdout JSON
+ * envelope, and the mapping from a finished hook run to what One Code should do
+ * about it. Envelope semantics follow Claude Code's hooks reference; the
+ * fail-closed choices are One Code's own (see docs/decisions.md).
+ */
+
+export type CcHookEvent =
+	| "PreToolUse"
+	| "PostToolUse"
+	| "UserPromptSubmit"
+	| "SessionStart"
+	| "Stop"
+	| "SessionEnd"
+	| "PreCompact"
+	| "PostCompact";
+
+export const CC_HOOK_EVENTS: readonly CcHookEvent[] = [
+	"PreToolUse",
+	"PostToolUse",
+	"UserPromptSubmit",
+	"SessionStart",
+	"Stop",
+	"SessionEnd",
+	"PreCompact",
+	"PostCompact",
+];
+
+/** What a hook command reads from stdin — Claude Code's field names exactly. */
+export interface HookStdinPayload {
+	session_id: string;
+	/** Empty string when the session has no file yet (e.g. --no-session). */
+	transcript_path: string;
+	cwd: string;
+	hook_event_name: CcHookEvent;
+	tool_name?: string;
+	tool_input?: Record<string, unknown>;
+	tool_response?: { content: unknown; is_error: boolean };
+	prompt?: string;
+	stop_hook_active?: boolean;
+	trigger?: "manual" | "auto";
+	source?: string;
+}
+
+export interface HookEnvelope {
+	continue?: boolean;
+	stopReason?: string;
+	suppressOutput?: boolean;
+	systemMessage?: string;
+	/** Legacy top-level fields, still emitted by many hook scripts. */
+	decision?: string;
+	reason?: string;
+	hookSpecificOutput?: {
+		hookEventName?: string;
+		permissionDecision?: string;
+		permissionDecisionReason?: string;
+		additionalContext?: string;
+		updatedInput?: Record<string, unknown>;
+		updatedToolResult?: unknown;
+	};
+}
+
+/** Parse a hook's stdout as the JSON envelope; non-JSON stdout is not an error. */
+export function parseEnvelope(stdout: string): HookEnvelope | undefined {
+	const trimmed = stdout.trim();
+	if (!trimmed.startsWith("{")) return undefined;
+	try {
+		const parsed: unknown = JSON.parse(trimmed);
+		return typeof parsed === "object" && parsed !== null ? (parsed as HookEnvelope) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** What one finished hook run asks One Code to do. */
+export interface HookOutcome {
+	block?: { reason: string };
+	updatedInput?: Record<string, unknown>;
+	updatedToolResult?: unknown;
+	additionalContext?: string;
+	systemMessage?: string;
+}
+
+export interface FinishedRun {
+	exitCode: number | null;
+	timedOut: boolean;
+	spawnError?: string;
+	stdout: string;
+	stderr: string;
+}
+
+/** Events where a hung or killed hook must fail closed rather than open. */
+const TIMEOUT_BLOCKS: ReadonlySet<CcHookEvent> = new Set(["PreToolUse", "UserPromptSubmit"]);
+/**
+ * Events where CC's plain (non-JSON) stdout becomes model-visible context
+ * rather than being discarded.
+ */
+const STDOUT_IS_CONTEXT: ReadonlySet<CcHookEvent> = new Set(["UserPromptSubmit", "SessionStart"]);
+
+export function interpretHookResult(event: CcHookEvent, run: FinishedRun): HookOutcome {
+	// Killed (timeout or otherwise): a null exit code must never read as a
+	// clean allow. Closed for the two events that gate something; open for the
+	// rest — the side effect already happened, or blocking would wedge exit.
+	if (run.timedOut || (run.exitCode === null && !run.spawnError)) {
+		return TIMEOUT_BLOCKS.has(event) ? { block: { reason: "Hook timed out" } } : {};
+	}
+	// A hook that couldn't spawn at all is an environment problem, not a
+	// verdict — fail open everywhere (CC treats non-2 errors as non-blocking).
+	if (run.spawnError) return {};
+
+	if (run.exitCode === 2) {
+		return { block: { reason: run.stderr.trim() || "Hook blocked the action (exit 2)" } };
+	}
+	if (run.exitCode !== 0) return {};
+
+	const envelope = parseEnvelope(run.stdout);
+	if (!envelope) {
+		const text = run.stdout.trim();
+		return text && STDOUT_IS_CONTEXT.has(event) ? { additionalContext: text } : {};
+	}
+
+	const outcome: HookOutcome = {};
+	const specific = envelope.hookSpecificOutput;
+
+	if (envelope.continue === false) {
+		outcome.block = { reason: envelope.stopReason?.trim() || "Hook stopped continuation" };
+	}
+	const decision = specific?.permissionDecision;
+	if (decision === "deny" || decision === "ask") {
+		// pi's tool_call is allow-or-block; treating "ask" as a silent allow
+		// would be the unsafe reading, so it blocks with the hook's reason.
+		outcome.block ??= {
+			reason:
+				specific?.permissionDecisionReason?.trim() ||
+				(decision === "ask" ? "Hook requested user confirmation" : "Hook denied the action"),
+		};
+	}
+	if (envelope.decision === "block") {
+		outcome.block ??= { reason: envelope.reason?.trim() || "Hook blocked the action" };
+	}
+	// "allow" is deliberately not handled: a hook cannot pre-approve anything —
+	// One Code's permission gate, safety floor, and classifier still run.
+
+	if (specific?.updatedInput && typeof specific.updatedInput === "object") {
+		outcome.updatedInput = specific.updatedInput;
+	}
+	if (specific && "updatedToolResult" in specific) outcome.updatedToolResult = specific.updatedToolResult;
+	if (specific?.additionalContext?.trim()) outcome.additionalContext = specific.additionalContext.trim();
+	if (envelope.systemMessage?.trim()) outcome.systemMessage = envelope.systemMessage.trim();
+	return outcome;
+}

package/extensions/hooks/settings.ts

@@ -0,0 +1,163 @@
+/**
+ * Hook config discovery and merge (pure fs reads, no pi imports).
+ *
+ * Sources, lowest authority first: user ~/.claude/settings.json, managed
+ * settings (Claude Code's platform paths), project .claude/settings.json,
+ * project .claude/settings.local.json. Project and local sources are
+ * *returned flagged, not filtered* — whether they run is a trust decision
+ * (hooks are arbitrary code execution) that index.ts applies via trust.ts;
+ * this module stays pure.
+ *
+ * Files are re-read only when their mtime changes: hook dispatch happens on
+ * every tool call, so the cache keeps that to a stat() per source, while
+ * config edits still land mid-session (unlike a session_start-only reload).
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { CC_HOOK_EVENTS, type CcHookEvent } from "./protocol.ts";
+
+export interface HookCommand {
+	type: "command";
+	command: string;
+	/** Seconds, CC convention. */
+	timeout?: number;
+}
+
+export interface HookMatcherEntry {
+	matcher?: string;
+	hooks: HookCommand[];
+}
+
+export type HooksFileConfig = Partial<Record<CcHookEvent, HookMatcherEntry[]>>;
+
+export type HookScope = "user" | "managed" | "project" | "local" | "plugin";
+
+export interface HooksSource {
+	scope: HookScope;
+	path: string;
+	pluginName?: string;
+	config: HooksFileConfig;
+}
+
+export interface LoadedHooks {
+	sources: HooksSource[];
+	/** Malformed entries are skipped and reported, never fatal. */
+	diagnostics: string[];
+}
+
+/** Managed-settings locations — Claude Code's exact per-platform paths. */
+export function managedSettingsPath(platform: NodeJS.Platform = process.platform): string {
+	if (platform === "darwin") return "/Library/Application Support/ClaudeCode/managed-settings.json";
+	if (platform === "win32") return "C:\\ProgramData\\ClaudeCode\\managed-settings.json";
+	return "/etc/claude-code/managed-settings.json";
+}
+
+export function hookSettingsPaths(claudeDir: string, cwd: string): Array<{ scope: HookScope; path: string }> {
+	return [
+		{ scope: "user", path: join(claudeDir, "settings.json") },
+		{ scope: "managed", path: managedSettingsPath() },
+		{ scope: "project", path: join(cwd, ".claude", "settings.json") },
+		{ scope: "local", path: join(cwd, ".claude", "settings.local.json") },
+	];
+}
+
+/**
+ * Validate one file's `hooks` block into HooksFileConfig. Unknown events,
+ * non-command hook types, and shape errors become diagnostics, not throws —
+ * a typo must not disable the rest of the user's hooks.
+ */
+export function parseHooksBlock(raw: unknown, origin: string, diagnostics: string[]): HooksFileConfig {
+	const config: HooksFileConfig = {};
+	if (raw === undefined || raw === null) return config;
+	if (typeof raw !== "object") {
+		diagnostics.push(`${origin}: "hooks" is not an object`);
+		return config;
+	}
+	for (const [event, entries] of Object.entries(raw as Record<string, unknown>)) {
+		if (!(CC_HOOK_EVENTS as readonly string[]).includes(event)) {
+			diagnostics.push(`${origin}: unsupported hook event "${event}" skipped`);
+			continue;
+		}
+		if (!Array.isArray(entries)) {
+			diagnostics.push(`${origin}: ${event} is not an array`);
+			continue;
+		}
+		const parsed: HookMatcherEntry[] = [];
+		for (const entry of entries) {
+			if (typeof entry !== "object" || entry === null || !Array.isArray((entry as { hooks?: unknown }).hooks)) {
+				diagnostics.push(`${origin}: ${event} entry without a hooks array skipped`);
+				continue;
+			}
+			const { matcher } = entry as { matcher?: unknown };
+			const hooks: HookCommand[] = [];
+			for (const hook of (entry as { hooks: unknown[] }).hooks) {
+				const candidate = hook as { type?: unknown; command?: unknown; timeout?: unknown };
+				if (candidate?.type !== "command" || typeof candidate.command !== "string" || !candidate.command.trim()) {
+					diagnostics.push(`${origin}: ${event} hook of type "${String(candidate?.type)}" skipped (only "command" is supported)`);
+					continue;
+				}
+				hooks.push({
+					type: "command",
+					command: candidate.command,
+					timeout: typeof candidate.timeout === "number" && candidate.timeout > 0 ? candidate.timeout : undefined,
+				});
+			}
+			if (hooks.length > 0) {
+				parsed.push({ matcher: typeof matcher === "string" ? matcher : undefined, hooks });
+			}
+		}
+		if (parsed.length > 0) config[event as CcHookEvent] = parsed;
+	}
+	return config;
+}
+
+interface CacheEntry {
+	mtimeMs: number;
+	config: HooksFileConfig;
+	diagnostics: string[];
+}
+
+const cache = new Map<string, CacheEntry>();
+
+/** Read one settings file's hooks block, via the mtime cache. */
+function readHooksFile(path: string, diagnostics: string[]): HooksFileConfig | undefined {
+	let mtimeMs: number;
+	try {
+		mtimeMs = statSync(path).mtimeMs;
+	} catch {
+		cache.delete(path);
+		return undefined;
+	}
+	const cached = cache.get(path);
+	if (cached && cached.mtimeMs === mtimeMs) {
+		diagnostics.push(...cached.diagnostics);
+		return cached.config;
+	}
+	const fileDiagnostics: string[] = [];
+	let config: HooksFileConfig = {};
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as { hooks?: unknown };
+		config = parseHooksBlock(parsed.hooks, path, fileDiagnostics);
+	} catch (error) {
+		fileDiagnostics.push(`${path}: unreadable settings file skipped (${error instanceof Error ? error.message : error})`);
+	}
+	cache.set(path, { mtimeMs, config, diagnostics: fileDiagnostics });
+	diagnostics.push(...fileDiagnostics);
+	return config;
+}
+
+export function loadHookSettings(claudeDir: string, cwd: string): LoadedHooks {
+	const diagnostics: string[] = [];
+	const sources: HooksSource[] = [];
+	for (const { scope, path } of hookSettingsPaths(claudeDir, cwd)) {
+		const config = readHooksFile(path, diagnostics);
+		if (config && Object.keys(config).length > 0) sources.push({ scope, path, config });
+	}
+	return { sources, diagnostics };
+}
+
+/** Test seam: drop the mtime cache. */
+export function resetHookSettingsCache(): void {
+	cache.clear();
+}

package/extensions/hooks/trust.ts

@@ -0,0 +1,151 @@
+/**
+ * Project-hook consent. Hooks in a repo's `.claude/settings.json` are
+ * arbitrary code execution the moment the repo is opened, so they run only
+ * after the user approves them — once per configuration: approval is keyed to
+ * a hash of the project+local hook config and persisted under `~/.one-code`, so
+ * it survives restarts but any change to the hooks re-prompts (Claude Code's
+ * own hooks-review behaviour). User, managed, and plugin hooks never prompt
+ * (installing a plugin was the consent).
+ *
+ * pi's own project-trust store is deliberately not reused: it only triggers
+ * on `.pi/*` resources, so a repo with only `.claude/settings.json` would
+ * never be asked — silently never approved.
+ *
+ * A declined prompt sticks for the process (module state), not on disk:
+ * "no" means "not this session", not "never ask again".
+ */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { oneCodeStateDir } from "../lib/paths.ts";
+import type { HooksSource } from "./settings.ts";
+
+interface ApprovalStore {
+	version: 1;
+	approvals: Record<string, { configHash: string; approvedAt: string }>;
+}
+
+export function approvalStorePath(): string {
+	return join(oneCodeStateDir(), "hooks", "project-approvals.json");
+}
+
+/** Key order must not change the hash — two spellings of one config are one consent. */
+function canonicalize(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (value && typeof value === "object") {
+		return Object.fromEntries(
+			Object.entries(value as Record<string, unknown>)
+				.sort(([a], [b]) => a.localeCompare(b))
+				.map(([key, inner]) => [key, canonicalize(inner)]),
+		);
+	}
+	return value;
+}
+
+export function hashProjectHooks(projectSources: HooksSource[]): string {
+	const canonical = JSON.stringify(projectSources.map((source) => [source.scope, canonicalize(source.config)]));
+	return createHash("sha256").update(canonical).digest("hex");
+}
+
+export function readStoredApproval(projectRoot: string, storePath = approvalStorePath()): string | undefined {
+	try {
+		const store = JSON.parse(readFileSync(storePath, "utf-8")) as ApprovalStore;
+		return store.approvals?.[projectRoot]?.configHash;
+	} catch {
+		return undefined;
+	}
+}
+
+export function persistApproval(projectRoot: string, configHash: string, storePath = approvalStorePath()): void {
+	let store: ApprovalStore = { version: 1, approvals: {} };
+	try {
+		const existing = JSON.parse(readFileSync(storePath, "utf-8")) as ApprovalStore;
+		if (existing && typeof existing === "object" && existing.approvals) store = existing;
+	} catch {
+		// Fresh store.
+	}
+	store.approvals[projectRoot] = { configHash, approvedAt: new Date().toISOString() };
+	try {
+		mkdirSync(dirname(storePath), { recursive: true });
+		writeFileSync(storePath, `${JSON.stringify(store, null, "\t")}\n`);
+	} catch {
+		// Approval still holds for this session; it will just re-prompt next run.
+	}
+}
+
+/** A short human summary of what the project wants to run, for the consent dialog. */
+export function describeProjectHooks(projectSources: HooksSource[]): string {
+	const commands: string[] = [];
+	for (const source of projectSources) {
+		for (const entries of Object.values(source.config)) {
+			for (const entry of entries) {
+				for (const hook of entry.hooks) commands.push(hook.command);
+			}
+		}
+	}
+	const shown = commands.slice(0, 5).map((cmd) => (cmd.length > 80 ? `${cmd.slice(0, 80)}…` : cmd));
+	const more = commands.length > shown.length ? `\n… and ${commands.length - shown.length} more` : "";
+	return `${commands.length} command hook(s):\n${shown.join("\n")}${more}`;
+}
+
+export interface TrustDecisionDeps {
+	hasUI: boolean;
+	confirm: (title: string, message: string) => Promise<boolean | undefined>;
+	notify: (message: string) => void;
+	storePath?: string;
+}
+
+/** Process-lifetime memory of declined/approved hashes per project, so a dispatch storm asks once. */
+const sessionDecisions = new Map<string, boolean>();
+const pendingPrompts = new Map<string, Promise<boolean>>();
+
+/**
+ * Whether the project/local hook sources may run. Resolves without prompting
+ * when the stored approval matches; otherwise prompts once (concurrent
+ * dispatches share the in-flight prompt) and persists a yes.
+ */
+export async function projectHooksApproved(
+	projectRoot: string,
+	projectSources: HooksSource[],
+	deps: TrustDecisionDeps,
+): Promise<boolean> {
+	if (projectSources.length === 0) return true;
+	const configHash = hashProjectHooks(projectSources);
+	const key = `${projectRoot}:${configHash}`;
+
+	const remembered = sessionDecisions.get(key);
+	if (remembered !== undefined) return remembered;
+	if (readStoredApproval(projectRoot, deps.storePath) === configHash) {
+		sessionDecisions.set(key, true);
+		return true;
+	}
+	if (!deps.hasUI) {
+		sessionDecisions.set(key, false);
+		deps.notify("Project hooks skipped: not yet approved and no UI to ask (user/managed hooks still run).");
+		return false;
+	}
+
+	let pending = pendingPrompts.get(key);
+	if (!pending) {
+		pending = (async () => {
+			const approved =
+				(await deps.confirm(
+					"Run this project's hooks?",
+					`This project's .claude settings define ${describeProjectHooks(projectSources)}\n\nThey run as shell commands on your machine. Approval is remembered until the hook config changes.`,
+				)) === true;
+			sessionDecisions.set(key, approved);
+			if (approved) persistApproval(projectRoot, configHash, deps.storePath);
+			else deps.notify("Project hooks disabled for this session (user/managed hooks still run).");
+			return approved;
+		})().finally(() => pendingPrompts.delete(key));
+		pendingPrompts.set(key, pending);
+	}
+	return pending;
+}
+
+/** Test seam. */
+export function resetTrustSessionState(): void {
+	sessionDecisions.clear();
+	pendingPrompts.clear();
+}

package/extensions/lib/branch-restore.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared "restore latest tool-result details from branch history" scan.
+ *
+ * Several extensions (todo, tasks, worktree) keep their live state in
+ * tool-result `details`, so branching or resuming a session can rebuild it by
+ * replaying `ctx.sessionManager.getBranch()`. Each one only wants the LAST
+ * matching result that counts as a real state update — a failed or no-op call
+ * (e.g. a refused exit_worktree) still produces a toolResult with the right
+ * toolName, but its details must not clobber an earlier valid restore point.
+ * `isValid` is exactly that per-site validity check.
+ *
+ * A forward loop that only overwrites its running value when `isValid` holds
+ * is equivalent to "the last entry for which `isValid` holds wins" — entries
+ * that fail the check are no-ops for the running value. So scanning backward
+ * and returning at the first entry that passes `isValid` reproduces the same
+ * result without walking the rest of the branch.
+ */
+
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export function restoreLatestDetails<T>(
+	branch: SessionEntry[],
+	toolNames: ReadonlySet<string>,
+	isValid: (details: T | undefined) => boolean = (details) => details !== undefined,
+): T | undefined {
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (entry.type !== "message") continue;
+		const msg = entry.message;
+		if (msg.role !== "toolResult" || !toolNames.has(msg.toolName)) continue;
+		const details = msg.details as T | undefined;
+		if (isValid(details)) return details;
+	}
+	return undefined;
+}

package/extensions/lib/claude-context.ts

@@ -0,0 +1,148 @@
+/**
+ * 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).
+ *
+ * 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.
+ *
+ * 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
+ * down to the cwd. (pi's resource-loader prefers AGENTS.md over CLAUDE.md per
+ * dir and omits CLAUDE.local.md / MEMORY.md, so it can't produce these bytes.)
+ *
+ * What is NOT yet replicated: enterprise-policy files and nested subtree
+ * CLAUDE.md loaded on-demand when a file under them is read (a follow-up needing
+ * file-tracker integration; absent from every turn-1 capture we have).
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tryReadFile } from "./plugins.ts";
+
+/** One CLAUDE.md-family file as it appears in the block. `content` is raw (untrimmed). */
+export interface ContextFile {
+	path: string;
+	content: string;
+	descriptor: string;
+}
+
+export const GLOBAL_DESCRIPTOR = "user's private global instructions for all projects";
+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";
+
+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.";
+
+function readFileIfPresent(path: string): string | null {
+	try {
+		if (!existsSync(path) || !statSync(path).isFile()) return null;
+	} catch {
+		return null;
+	}
+	const content = tryReadFile(path);
+	return content === undefined ? null : content;
+}
+
+/**
+ * Claude Code's CLAUDE.md discovery, ordered as it appears in the block: global
+ * first, then project files from the farthest ancestor down to the cwd. Within a
+ * directory, `CLAUDE.md` then `CLAUDE.local.md`. `homeClaudeDir` is `~/.claude`.
+ */
+export function discoverContextFiles(opts: {
+	cwd: string;
+	homeClaudeDir: string;
+}): ContextFile[] {
+	const files: ContextFile[] = [];
+	const seen = new Set<string>();
+
+	const globalPath = join(opts.homeClaudeDir, "CLAUDE.md");
+	const globalContent = readFileIfPresent(globalPath);
+	if (globalContent !== null) {
+		files.push({ path: globalPath, content: globalContent, descriptor: GLOBAL_DESCRIPTOR });
+		seen.add(globalPath);
+	}
+
+	// Walk cwd → root collecting directories, then emit farthest-ancestor first.
+	const dirs: string[] = [];
+	let dir = opts.cwd;
+	while (true) {
+		dirs.unshift(dir);
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+
+	for (const d of dirs) {
+		for (const [name, descriptor] of [
+			["CLAUDE.md", PROJECT_DESCRIPTOR],
+			["CLAUDE.local.md", LOCAL_DESCRIPTOR],
+		] as const) {
+			const p = join(d, name);
+			if (seen.has(p)) continue;
+			const content = readFileIfPresent(p);
+			if (content !== null) {
+				files.push({ path: p, content, descriptor });
+				seen.add(p);
+			}
+		}
+	}
+
+	return files;
+}
+
+/**
+ * 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:
+ *
+ *   {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}
+ *
+ * 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.
+ */
+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()) {
+		sections.push({
+			path: opts.memoryIndex.path,
+			content: opts.memoryIndex.content,
+			descriptor: MEMORY_DESCRIPTOR,
+		});
+	}
+
+	if (sections.length === 0 && !opts.email) return null;
+
+	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;
+}