@junghanacs/entwurf 0.12.0

package/pi-extensions/lib/acp/acp-client.ts

@@ -0,0 +1,90 @@
+// ACP client adapter — the ONE place that touches the @agentclientprotocol/sdk
+// 0.29 fluent surface (`client({ name }).connect(stream)`).
+//
+// The wire SDK deprecated the `new ClientSideConnection(toClient, stream)`
+// constructor in favour of the fluent `client()` builder. The two have
+// different shapes: the deprecated class implemented `Agent` directly (so
+// `.initialize()`/`.newSession()`/`.prompt()` were methods on the returned
+// object), while `client(...).connect(stream)` returns a persistent
+// `ClientConnection` whose `.agent` is a `ClientContext` driven by
+// `request(<method>, params)`.
+//
+// `connect()` (NOT `connectWith()`) is the right primitive here: the backend
+// retains the connection on a BridgeSession and reuses it across turns
+// (backend.ts), so the op-scoped close semantics of `connectWith` do not fit.
+//
+// This module owns the `AcpConnectionLike` seam so the backend and the live
+// smokes both drive ONE adapter — the SDK method-name mapping lives here only,
+// and the backend's orchestration + the gate fakes stay untouched.
+
+import { AGENT_METHODS, CLIENT_METHODS, client, type Stream } from "@agentclientprotocol/sdk";
+import type { AcpTextBlock } from "./context.js";
+
+/** The subset of the ACP agent connection the backend drives (real or fake). */
+export interface AcpConnectionLike {
+	initialize(params: unknown): Promise<unknown>;
+	newSession(params: unknown): Promise<{ sessionId?: string }>;
+	prompt(params: { sessionId: string; prompt: AcpTextBlock[] }): Promise<{ stopReason?: string }>;
+	setSessionConfigOption?(params: unknown): Promise<unknown>;
+	/**
+	 * Closes the underlying SDK connection before child process teardown. With
+	 * the fluent SDK connection this is load-bearing: otherwise a successful
+	 * live turn can print PASS but keep Node's event loop alive.
+	 *
+	 * Implementations MUST be best-effort (never throw): callers invoke it on
+	 * success, error, and reuse-error teardown paths, so a close failure must not
+	 * mask the turn's real outcome nor skip the child teardown that follows it.
+	 */
+	close?(error?: unknown): void;
+}
+
+/** The ACP client-side callbacks. They delegate to the session's mutable handler. */
+export interface AcpClientHandlers {
+	sessionUpdate(notification: { update?: Record<string, unknown>; sessionId?: string }): Promise<void>;
+	requestPermission(request: { options?: Array<{ optionId: string; kind?: string }> }): Promise<{
+		outcome: { outcome: "selected"; optionId: string } | { outcome: "cancelled" };
+	}>;
+	readTextFile(request: { path: string }): Promise<{ content: string }>;
+	// `void` (not `never`): the backend's handler denies by throwing, but the
+	// shared smokes legitimately return a write response ({}); both satisfy the
+	// SDK's `WriteTextFileResponse | void` handler contract.
+	writeTextFile(request: unknown): Promise<void>;
+}
+
+/**
+ * Production factory — wrap the SDK 0.29 fluent `client()` into the
+ * `AcpConnectionLike` seam the backend (and the live smokes) drive.
+ *
+ * Client-side handlers register by ACP method name; agent-side calls go through
+ * the persistent connection's `ClientContext` (`conn.agent`). Both the params a
+ * handler receives (`ctx.params`) and the throw-to-JSON-RPC-error behaviour
+ * match the deprecated `ClientSideConnection`, so this is behaviour-preserving.
+ */
+export function connectAcpClient(stream: Stream, handlers: AcpClientHandlers): AcpConnectionLike {
+	const conn = client({ name: "entwurf" })
+		.onNotification(CLIENT_METHODS.session_update, (ctx) => handlers.sessionUpdate(ctx.params as never))
+		.onRequest(CLIENT_METHODS.session_request_permission, (ctx) => handlers.requestPermission(ctx.params as never))
+		.onRequest(CLIENT_METHODS.fs_read_text_file, (ctx) => handlers.readTextFile(ctx.params as never))
+		.onRequest(CLIENT_METHODS.fs_write_text_file, (ctx) => handlers.writeTextFile(ctx.params as never))
+		.connect(stream);
+
+	const agent = conn.agent;
+	return {
+		initialize: (params) => agent.request(AGENT_METHODS.initialize, params as never),
+		newSession: (params) =>
+			agent.request(AGENT_METHODS.session_new, params as never) as Promise<{ sessionId?: string }>,
+		prompt: (params) =>
+			agent.request(AGENT_METHODS.session_prompt, params as never) as Promise<{ stopReason?: string }>,
+		setSessionConfigOption: (params) => agent.request(AGENT_METHODS.session_set_config_option, params as never),
+		close: (error) => {
+			// Best-effort by contract (see AcpConnectionLike.close): a teardown-path
+			// close that threw would mask the turn's real error and skip the child
+			// teardown that runs after it.
+			try {
+				conn.close(error);
+			} catch {
+				// connection already closed / SDK teardown race — nothing to recover.
+			}
+		},
+	};
+}

package/pi-extensions/lib/acp/augment.ts

@@ -0,0 +1,238 @@
+// ACP plugin — first-user-message context augment + entwurf de-dup (S2d-1c).
+//
+// The rich context the ACP-side agent needs — bridge identity, the
+// task-execution stance, pi's base intro + tool surface, the operator's
+// `~/AGENTS.md`, the project's `cwd/AGENTS.md`, date + cwd — is delivered as a
+// text block PREPENDED to the first prompt of a `bootstrapPath="new"` session,
+// NOT via `_meta.systemPrompt`.
+//
+// Why first-user-message and not the carrier (NEXT §S2-scout 핀1, oracle A):
+// growing `_meta.systemPrompt` materially past the SDK-default size reclassifies a
+// subscription call as metered → HTTP 400. A long FIRST USER MESSAGE is
+// structurally identical to any other user prompt and does not touch billing
+// classification, so the rich context rides here while engraving.ts keeps the
+// carrier tiny (a small non-empty string whose real job is replacing the preset
+// to strip auto-memory, not carrying context).
+//
+// once-only (NEXT §S2d gate ②, GPT c32a6c8): this augment is prepended to the
+// `new` prompt ONLY. `new` happens exactly once per ACP session lifecycle
+// (subsequent turns are `reuse` delta-only; an incompatible drift opens a
+// genuinely new ACP session that correctly gets the augment again). The augment
+// is prepended at the WIRE level (to the AcpTextBlock[]), never mutated into the
+// pi Context, so `contextMessageSignatures(context)` never sees it — that is what
+// keeps the augment out of the reuse-compat signature with no extra bookkeeping.
+//
+// Entwurf de-dup: when an entwurf-spawned task is the first user message,
+// `enrichTaskWithProjectContext` (entwurf-core.ts) has already prepended a
+// `<project-context path="${cwd}/AGENTS.md">` block carrying the cwd AGENTS.md.
+// Augmenting that prompt with the SAME cwd AGENTS.md section would duplicate it,
+// so we drop only the cwd-AGENTS section and keep the rest of the augment.
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ENTWURF_PROJECT_CONTEXT_OPEN_TAG } from "../../../protocol.js";
+import type { AcpTextBlock } from "./context.js";
+
+const MAX_AUGMENT_BYTES = 50 * 1024;
+
+export interface PiContextAugmentParams {
+	/** Claude-only this cut; kept as a field so the narrative names the backend. */
+	backend: string;
+	cwd: string;
+	mcpServerNames: readonly string[];
+	emacsAgentSocket?: string;
+	/** Home dir to read `~/AGENTS.md` from. Defaults to os.homedir() (gate seam). */
+	homeDir?: string;
+}
+
+/**
+ * Build the augment text to prepend to the first user message of a NEW ACP
+ * session. Day-granularity date so two prompts on the same calendar day produce
+ * the same augment. Truncated to 50KB. Pure w.r.t. (cwd, backend, sorted
+ * mcpServerNames, AGENTS.md contents, calendar day).
+ */
+export function buildPiContextAugment(params: PiContextAugmentParams): string {
+	const names = [...params.mcpServerNames].sort();
+	const mcpList = names.length > 0 ? names.join(", ") : "(none registered)";
+
+	const sections: string[] = [];
+
+	// Bridge identity + caller-side sibling stance. The closing line is a
+	// caller-perspective statement: when THIS session throws an entwurf, the peer
+	// on the other end is a sibling, not a worker.
+	sections.push(
+		[
+			"You are operating through entwurf, an ACP bridge between pi (the harness) and the underlying model.",
+			`Backend: ${params.backend}.`,
+			`Connected MCP servers: ${mcpList}.`,
+			"When entwurf is invoked, you do not spawn workers — you summon sibling agents through this bridge.",
+		].join("\n"),
+	);
+
+	// Receiver-side task-execution stance. A SEPARATE paragraph so the caller
+	// stance above does not bleed into how incoming tasks are read.
+	sections.push(
+		"A task is a task: execute what you receive, regardless of transport (spawn/resume/send) or source (GLG or sibling). The only thing you do not do on your own is forward your task to another sibling — if you cannot or should not do it, say so to GLG instead.",
+	);
+
+	sections.push(
+		[
+			"You are an expert coding assistant operating inside pi, a coding agent harness.",
+			"You help users by reading files, executing commands, editing code, and writing new files.",
+			"",
+			"Tool surface:",
+			"- Treat the actual callable function/tool schema exposed in this session as the source of truth.",
+			"- Do not assume a tool exists only because this context or AGENTS.md mentions it.",
+			"- Pi-level work generally includes reading files, running shell commands, editing files, and writing files; concrete tool names differ by backend.",
+			"- Native pi may expose read/bash/edit/write; Claude ACP may expose Read/Bash/Edit/Write/Skill; Codex ACP may expose exec_command/apply_patch/write_stdin/update_plan.",
+			"- MCP/custom tools are usable only when they appear in the actual tool schema for this session.",
+		].join("\n"),
+	);
+
+	if (params.emacsAgentSocket) {
+		sections.push(
+			[
+				"Emacs integration:",
+				`- Agent Emacs socket: ${params.emacsAgentSocket}`,
+				'- When using emacsclient from shell/Bash, prefer `emacsclient -s "$PI_EMACS_AGENT_SOCKET" --eval ...`.',
+				"- Do not hardcode `-s server` unless the user explicitly asks for that socket.",
+			].join("\n"),
+		);
+	}
+
+	const projectContextParts: string[] = [];
+	const homeBase = params.homeDir ?? homedir();
+	const homeAgents = join(homeBase, "AGENTS.md");
+	const cwdAgents = join(params.cwd, "AGENTS.md");
+
+	if (existsSync(homeAgents)) {
+		const content = readAgents(homeAgents);
+		if (content) projectContextParts.push(`## ${homeAgents}\n\n${content}`);
+	}
+	if (existsSync(cwdAgents) && cwdAgents !== homeAgents) {
+		const content = readAgents(cwdAgents);
+		if (content) projectContextParts.push(`## ${cwdAgents}\n\n${content}`);
+	}
+
+	if (projectContextParts.length > 0) {
+		sections.push(
+			["# Project Context", "", "Project-specific instructions and guidelines:", "", ...projectContextParts].join("\n"),
+		);
+	}
+
+	const currentDate = new Intl.DateTimeFormat("en-CA", {
+		timeZone: "Asia/Seoul",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	}).format(new Date());
+	sections.push([`Current date: ${currentDate}`, `Current working directory: ${params.cwd}`].join("\n"));
+
+	return truncateAugment(sections.join("\n\n"));
+}
+
+function readAgents(filePath: string): string {
+	try {
+		return readFileSync(filePath, "utf8").trim();
+	} catch (error) {
+		throw new Error(
+			`Failed to read AGENTS.md at ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+function truncateAugment(text: string): string {
+	if (Buffer.byteLength(text, "utf8") <= MAX_AUGMENT_BYTES) return text;
+	const marker = `\n\n[entwurf: context augment truncated to ${MAX_AUGMENT_BYTES} bytes; read AGENTS.md files directly if more detail is needed.]`;
+	const markerBytes = Buffer.byteLength(marker, "utf8");
+	let end = text.length;
+	while (end > 0 && Buffer.byteLength(text.slice(0, end), "utf8") + markerBytes > MAX_AUGMENT_BYTES) {
+		end = Math.max(0, end - 1024);
+	}
+	while (end < text.length && Buffer.byteLength(text.slice(0, end + 1), "utf8") + markerBytes <= MAX_AUGMENT_BYTES) {
+		end++;
+	}
+	return `${text.slice(0, end).trimEnd()}${marker}`;
+}
+
+/** trimEnd + a trailing blank line so the augment block reads as its own unit. */
+function ensurePromptSeparator(text: string): string {
+	const trimmed = text.trimEnd();
+	return trimmed.length > 0 ? `${trimmed}\n\n` : trimmed;
+}
+
+/**
+ * The exact opening tag `enrichTaskWithProjectContext` emits for THIS cwd. The
+ * path is included so the check cannot false-match a project-context block for a
+ * different directory.
+ */
+function entwurfCwdContextOpenTag(cwd: string): string {
+	return `${ENTWURF_PROJECT_CONTEXT_OPEN_TAG} path="${join(cwd, "AGENTS.md")}">`;
+}
+
+/**
+ * True when the prompt we are about to send already carries the entwurf
+ * project-context block for this cwd (so the augment's cwd-AGENTS section would
+ * duplicate it). In this cut the `new` prompt is the whole flattened transcript,
+ * so the marker can sit anywhere inside it — `includes`, not `startsWith`.
+ */
+export function promptCarriesEntwurfCwdContext(promptText: string, cwd: string): boolean {
+	return promptText.includes(entwurfCwdContextOpenTag(cwd));
+}
+
+/**
+ * Remove ONLY the `## ${cwd}/AGENTS.md` subsection from the augment, keeping the
+ * bridge narrative, pi base, home AGENTS.md, and date/cwd. If dropping it leaves
+ * the "# Project Context" section with no remaining subsection, drop the empty
+ * header too. Ported verbatim from 0.11.0 acp-bridge.ts.
+ */
+export function removeCwdAgentsSectionFromAugment(text: string, cwd: string): string {
+	const heading = `## ${join(cwd, "AGENTS.md")}\n\n`;
+	const start = text.indexOf(heading);
+	if (start < 0) return text;
+
+	const afterHeading = start + heading.length;
+	const nextProjectHeading = text.indexOf("\n\n## ", afterHeading);
+	const currentDateSection = text.indexOf("\n\nCurrent date:", afterHeading);
+	const candidates = [nextProjectHeading, currentDateSection].filter((idx) => idx >= 0);
+	const end = candidates.length > 0 ? Math.min(...candidates) : text.length;
+	let result = `${text.slice(0, start).trimEnd()}${text.slice(end)}`;
+
+	const projectHeader = "# Project Context\n\nProject-specific instructions and guidelines:";
+	const projectStart = result.indexOf(projectHeader);
+	if (projectStart >= 0) {
+		const projectEnd = result.indexOf("\n\nCurrent date:", projectStart + projectHeader.length);
+		const projectBody =
+			projectEnd >= 0
+				? result.slice(projectStart + projectHeader.length, projectEnd)
+				: result.slice(projectStart + projectHeader.length);
+		if (!projectBody.includes("\n## ")) {
+			result =
+				projectEnd >= 0
+					? `${result.slice(0, projectStart).trimEnd()}${result.slice(projectEnd)}`
+					: result.slice(0, projectStart).trimEnd();
+		}
+	}
+
+	return result.trim();
+}
+
+/**
+ * Prepend the first-user-message augment to a `new` session's prompt blocks.
+ *
+ * De-dup: if `promptBlocks` already carry the entwurf project-context for this
+ * cwd, the augment's cwd-AGENTS section is dropped first. The pi Context is NEVER
+ * touched — the augment lives only on the wire, so it stays out of
+ * `contextMessageSignatures`. A whitespace-only augment is omitted entirely.
+ */
+export function prependNewPromptAugment(promptBlocks: AcpTextBlock[], params: PiContextAugmentParams): AcpTextBlock[] {
+	const promptText = promptBlocks.map((b) => b.text).join("\n");
+	let augment = buildPiContextAugment(params);
+	if (promptCarriesEntwurfCwdContext(promptText, params.cwd)) {
+		augment = removeCwdAgentsSectionFromAugment(augment, params.cwd);
+	}
+	const separated = ensurePromptSeparator(augment);
+	if (!separated) return promptBlocks;
+	return [{ type: "text", text: separated }, ...promptBlocks];
+}

package/pi-extensions/lib/acp/backend-adapter.ts

@@ -0,0 +1,319 @@
+// ACP backend adapter rail — the PRODUCT seam by which a curated model id selects
+// which ACP backend (claude / future backend / …) drives a turn. See docs/acp-backend-rail.md §9.
+//
+// This seam is DISTINCT from `AcpTurnDeps` (backend.ts), which is the test/runtime
+// seam (fake spawn/connection/clock for the gates). The two are kept apart on
+// purpose (GPT-agreed §9-2): merging them would make a fake-deps fixture look like
+// a fake backend and force the adapter to carry clock/sessionDir/createConnection.
+// The wiring is `defaultDeps(adapter)` — the turn loop in backend.ts stays
+// backend-invariant; only these per-backend functions change with `adapter`.
+//
+// STATUS: Step A+B done — backend.ts is wired to this rail. The turn loop in
+// backend.ts delegates every per-backend step through the resolved adapter
+// (resolveLaunch/ensureOverlay/loadCarrier/buildSessionMeta/enforceModel/
+// launchEnvDefaults); there is no private resolveLaunch copy in backend.ts.
+// `resolveClaudeLaunch` below is the single source for the claude launch spec.
+//
+// Fence: imported by the root program with `.js` suffixes, same as the sibling
+// lib/acp modules — no new strip-types fence.
+
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+import type { AcpConnectionLike } from "./acp-client.js";
+import type { ResolvedAcpConfig } from "./config.js";
+import { loadEngraving } from "./engraving.js";
+import { curatedClaudeModels, SUPPORTED_ANTHROPIC_MODEL_IDS } from "./models.js";
+import { claudeLaunchEnvDefaults, ensureClaudeConfigOverlay } from "./overlay.js";
+import { buildClaudeSessionMeta } from "./tool-surface.js";
+
+// ---------------------------------------------------------------------------
+// Shared shapes
+// ---------------------------------------------------------------------------
+
+/** Launch spec for the ACP server child process. */
+export interface AcpLaunchSpec {
+	command: string;
+	args: string[];
+}
+
+/** A curated provider model row (the shape pi.registerProvider({ models }) takes). */
+export type AcpModelRow = ReturnType<typeof curatedClaudeModels>[number];
+
+/** routeModel result — the backend-native model id with the curation prefix stripped. */
+export interface AcpRoutedModel {
+	nativeModelId: string;
+}
+
+/** resolveLaunch input — native (prefix-stripped) model id + resolved operator config. */
+export interface AcpLaunchParams {
+	cwd: string;
+	modelId: string;
+	nativeModelId: string;
+	config: ResolvedAcpConfig;
+}
+
+/** loadCarrier input — the mcp server names plus the resolved config (so a backend
+ *  whose carrier depends on its own `config.adapterSettings` can read it). backend.ts
+ *  still never inspects config — it just passes it through. */
+export interface AcpCarrierParams {
+	mcpServerNames: string[];
+	config: ResolvedAcpConfig;
+}
+
+/** ensureOverlay input — cwd + (native) model id + the resolved config. A backend
+ *  whose overlay/env depends on its OWN settings reads them off `config.adapterSettings`
+ *  here; backend.ts never inspects config. Same shape as AcpLaunchParams (overlay and
+ *  launch are distinct phases, so they keep distinct names). */
+export interface AcpOverlayParams {
+	cwd: string;
+	modelId: string;
+	nativeModelId: string;
+	config: ResolvedAcpConfig;
+}
+
+/** buildSessionMeta input — mirrors the newSession `_meta` inputs. */
+export interface AcpSessionMetaParams {
+	modelId: string;
+	nativeModelId: string;
+	config: ResolvedAcpConfig;
+}
+
+/** enforceModel input — the live connection + acp session + native id. */
+export interface AcpEnforceModelParams {
+	connection: AcpConnectionLike;
+	acpSessionId: string;
+	modelId: string;
+	nativeModelId: string;
+}
+
+/** ensureOverlay result — env overrides backend.ts merges into the spawn env. */
+export interface AcpOverlayResult {
+	envOverrides: Record<string, string>;
+}
+
+/** resolveAdapterSettings input — the RAW (untyped) `entwurfProvider` blocks plus
+ *  their file paths. This is the ONE seam by which a backend reads its OWN settings
+ *  (e.g. a connection id, a profile/tenant, a state-home path) WITHOUT those
+ *  backend-specific keys ever touching the common ResolvedAcpConfig (fat-bridge
+ *  regression). `mergedBlock` is
+ *  the project-over-global merge (project keys win); the per-file blocks + paths are
+ *  for error attribution. A backend with no own settings returns `undefined`. */
+export interface AcpAdapterSettingsParams {
+	globalBlock: Record<string, unknown>;
+	projectBlock: Record<string, unknown>;
+	mergedBlock: Record<string, unknown>;
+	globalPath: string;
+	projectPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// The adapter interface
+// ---------------------------------------------------------------------------
+
+export interface AcpBackendAdapter {
+	/** Discriminator. backend.ts stores this on BridgeSession/configSig so reuse
+	 *  and diagnostics never re-parse the model-id string. */
+	readonly backend: string;
+
+	/** Does this adapter own `modelId`? If so, return the backend-native id (prefix
+	 *  stripped); else undefined. Returning the native id here (vs a bare boolean)
+	 *  keeps the registry from leaning on adapter order and gives resolveLaunch /
+	 *  enforceModel the value they must actually send to the backend. */
+	routeModel(modelId: string): AcpRoutedModel | undefined;
+
+	/** Curated model rows this backend contributes to the single `entwurf` provider. */
+	curatedModels(): AcpModelRow[];
+
+	/** Parse this backend's OWN settings from the raw entwurfProvider blocks, returning
+	 *  an opaque value config.ts stores on `ResolvedAcpConfig.adapterSettings`. backend.ts
+	 *  NEVER inspects the result; only this adapter's other methods read it (casting their
+	 *  own type back). A backend with no own settings returns `undefined`. This keeps the
+	 *  common config free of backend-named fields (see AcpAdapterSettingsParams). */
+	resolveAdapterSettings(params: AcpAdapterSettingsParams): unknown;
+
+	/** Resolve the ACP server launch (command + args), honoring an env override. */
+	resolveLaunch(params: AcpLaunchParams): AcpLaunchSpec;
+
+	/** Static launch env defaults merged over process.env at spawn. */
+	launchEnvDefaults(): Record<string, string>;
+
+	/** Materialize the config overlay (auth passthrough + state hiding) and return
+	 *  the env overrides to merge at spawn. A no-op backend returns { envOverrides: {} }.
+	 *  Receives the resolved config so a settings-dependent overlay can read its own
+	 *  `config.adapterSettings`; settings-derived spawn env rides the returned
+	 *  `envOverrides` (launchEnvDefaults stays static). */
+	ensureOverlay(params: AcpOverlayParams): AcpOverlayResult;
+
+	/** Render the optional short operator carrier (engraving). Kept SEPARATE from
+	 *  buildSessionMeta so backend.ts can load it ONCE and fold the same value into
+	 *  both the config signature and the session meta (they must agree). A carrier-
+	 *  less backend returns null WITHOUT calling loadEngraving, so it never trips the
+	 *  shipped-engraving / appendSystemPrompt signature. */
+	loadCarrier(params: AcpCarrierParams): string | null;
+
+	/** Build the `_meta` handed to newSession. `undefined` → backend.ts omits the
+	 *  `_meta` key entirely (carrier-less backend). Rich operator context rides the
+	 *  first-user augment regardless, never this carrier. */
+	buildSessionMeta(params: AcpSessionMetaParams, carrier: string | null): Record<string, unknown> | undefined;
+
+	/** Enforce the requested model on the live ACP session. Single method absorbs
+	 *  the per-backend difference (claude: per-turn session/set_config_option; a
+	 *  launch-pinned backend: no-op here). backend.ts wraps the call in withTimeout. */
+	enforceModel(params: AcpEnforceModelParams): Promise<void>;
+
+	/** Backend-specific fields folded into bridgeConfigSignature (reuse invalidation):
+	 *  connection/profile/env-derived STABLE ids only — never raw env values / secrets.
+	 *  Reads ONLY this backend's opaque `adapterSettings` (NOT the whole config), so the
+	 *  signature contract can never accidentally fold a common field. MUST be a flat,
+	 *  sorted-stable primitive map (JSON.stringify determinism — no nested objects /
+	 *  non-deterministic order). `backend` + `nativeModelId` are added by backend.ts. */
+	configSignatureFields(adapterSettings: unknown): Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// claude adapter — the first implementation (the rail's reference backend)
+// ---------------------------------------------------------------------------
+
+const SUPPORTED_CLAUDE_IDS: ReadonlySet<string> = new Set(SUPPORTED_ANTHROPIC_MODEL_IDS);
+
+/** Resolve the claude-agent-acp launch — package bin (resolve), env override for debug.
+ *  This is the single source for the claude launch spec; backend.ts holds no private copy. */
+function resolveClaudeLaunch(): AcpLaunchSpec {
+	const override = process.env.CLAUDE_AGENT_ACP_COMMAND?.trim();
+	if (override) return { command: "bash", args: ["-lc", override] };
+	const require = createRequire(import.meta.url);
+	const pkgJsonPath = require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
+	const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as { bin?: string | Record<string, string> };
+	const binPath = typeof pkgJson.bin === "string" ? pkgJson.bin : pkgJson.bin?.["claude-agent-acp"];
+	if (!binPath) throw new Error("@agentclientprotocol/claude-agent-acp resolved but exposes no bin entry");
+	return { command: process.execPath, args: [join(dirname(pkgJsonPath), binPath)] };
+}
+
+export const claudeAdapter: AcpBackendAdapter = {
+	backend: "claude",
+
+	// Claude owns its UNPREFIXED curated ids only (GPT-agreed §9-1). The native id
+	// equals the curated id — claude carries no curation prefix to strip.
+	routeModel(modelId) {
+		return SUPPORTED_CLAUDE_IDS.has(modelId) ? { nativeModelId: modelId } : undefined;
+	},
+
+	curatedModels() {
+		return curatedClaudeModels();
+	},
+
+	// Claude carries no backend-specific settings — its entire surface is common
+	// config (tools/permissions/settingSources/…). undefined → config.adapterSettings
+	// is undefined and no claude method reads it.
+	resolveAdapterSettings() {
+		return undefined;
+	},
+
+	resolveLaunch() {
+		return resolveClaudeLaunch();
+	},
+
+	launchEnvDefaults() {
+		return claudeLaunchEnvDefaults();
+	},
+
+	ensureOverlay() {
+		// Claude's overlay is constant (no settings dependence), so it ignores params.
+		ensureClaudeConfigOverlay();
+		// CLAUDE_CONFIG_DIR rides launchEnvDefaults(); the overlay materialization
+		// itself contributes no extra spawn env.
+		return { envOverrides: {} };
+	},
+
+	loadCarrier({ mcpServerNames }) {
+		// Claude's carrier is the shipped engraving — it does not read config.
+		return loadEngraving({ backend: "claude", mcpServerNames });
+	},
+
+	buildSessionMeta({ nativeModelId, config }, carrier) {
+		// buildClaudeSessionMeta always returns an object (it only omits the
+		// systemPrompt KEY when carrier is absent), so claude never yields undefined.
+		return buildClaudeSessionMeta(
+			{
+				modelId: nativeModelId,
+				tools: config.tools,
+				permissionAllow: config.permissionAllow,
+				disallowedTools: config.disallowedTools,
+				settingSources: config.settingSources,
+				strictMcpConfig: config.strictMcpConfig,
+				skillPlugins: config.skillPlugins,
+			},
+			carrier ?? undefined,
+		);
+	},
+
+	async enforceModel({ connection, acpSessionId, nativeModelId, modelId }) {
+		const setConfig = connection.setSessionConfigOption;
+		if (typeof setConfig !== "function") {
+			throw new Error(`setSessionConfigOption unsupported — cannot enforce model ${modelId}`);
+		}
+		await setConfig.call(connection, { sessionId: acpSessionId, configId: "model", value: nativeModelId });
+	},
+
+	configSignatureFields(_adapterSettings) {
+		// Claude folds no extra backend-specific fields beyond backend + nativeModelId
+		// (which backend.ts adds). A future backend reads its own stable id off
+		// `_adapterSettings` here.
+		return {};
+	},
+};
+
+// ---------------------------------------------------------------------------
+// Registry — modelId → adapter
+// ---------------------------------------------------------------------------
+
+/** Registered adapters. Order carries NO routing authority — routeModel decides.
+ *  Step A: claude only. A second backend appends here with its reserved prefix
+ *  (e.g. `<backend>-*`), and the fail-fast below proves no two adapters claim one id. */
+const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter];
+
+/**
+ * Resolve the backend adapter that owns `modelId`.
+ *
+ * GPT-agreed §9-1 fail-fast contract:
+ *  - 0 matches  → throw (unknown model — no silent default).
+ *  - 2+ matches → throw (prefix collision — a startup-visible registry bug).
+ *
+ * The thrown native id is recovered from the single matching adapter's routeModel,
+ * so callers get `{ adapter, nativeModelId }` and never re-parse the id string.
+ */
+export function resolveAcpBackendAdapter(modelId: string): { adapter: AcpBackendAdapter; nativeModelId: string } {
+	const matches: Array<{ adapter: AcpBackendAdapter; nativeModelId: string }> = [];
+	for (const adapter of ADAPTERS) {
+		const routed = adapter.routeModel(modelId);
+		if (routed) matches.push({ adapter, nativeModelId: routed.nativeModelId });
+	}
+	if (matches.length === 0) {
+		throw new Error(`entwurf: no ACP backend adapter owns model id ${JSON.stringify(modelId)}`);
+	}
+	if (matches.length > 1) {
+		const owners = matches.map((m) => m.adapter.backend).join(", ");
+		throw new Error(`entwurf: model id ${JSON.stringify(modelId)} is claimed by multiple adapters (${owners})`);
+	}
+	return matches[0];
+}
+
+/** Every curated model row across all registered adapters — for provider registration.
+ *  GPT-agreed §9-6 registration-time fail-fast: every curated id must route to EXACTLY
+ *  one adapter and no id may be duplicated across adapters. Catching it here means a
+ *  prefix-collision / duplicate surfaces at provider registration, not mid-turn. */
+export function allCuratedModels(): AcpModelRow[] {
+	const rows = ADAPTERS.flatMap((adapter) => adapter.curatedModels());
+	const seen = new Set<string>();
+	for (const row of rows) {
+		if (seen.has(row.id)) {
+			throw new Error(`entwurf: duplicate curated model id across ACP backend adapters: ${row.id}`);
+		}
+		seen.add(row.id);
+		// Throws on 0 matches (unowned) or 2+ matches (prefix collision).
+		resolveAcpBackendAdapter(row.id);
+	}
+	return rows;
+}