@junghanacs/entwurf 0.52.0 → 0.53.1

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/models.js

@@ -1,18 +1,12 @@
-// ACP plugin — curated model surface (S0 loader/fence slice; cortex rows added
-// in 0.13).
+// ACP plugin — curated Claude model surface. Cortex ACP is disabled.
 //
 // entwurf is an ACP *plugin* on the v2 core, NOT a general-purpose
 // Anthropic provider. It deliberately does not expose the full pi-ai model
 // registry — the surface is curated to the ids the plugin commits to driving
 // through a real ACP backend.
 //
-// Two curated sets live here, one per adapter on the rail
-// (backend-adapter.ts): the unprefixed Claude ids (the reference backend) and
-// the `cortex-` prefixed Snowflake Cortex Code ids (the second backend, landed
-// 0.13.0 — docs/acp-backend-rail.md “Cortex Code audit”). Codex has native
-// delivery-probe evidence but no managed citizen lane; neither it nor Gemini is an ACP backend here.
-// A third governed backend EXTENDS this file the same way — it does not change
-// the pattern.
+// Only the unprefixed Claude IDs are registered. Historical Cortex IDs are
+// reserved refusal inputs; native citizens are independent of this provider.
 // pi 0.80 migration: the standalone root `getModels()` moved to the deprecated
 // `@earendil-works/pi-ai/compat` entrypoint (the global-API churn). We import it
 // from `/compat` directly.
@@ -36,7 +30,7 @@ import { CURATED_ANCHOR_MODEL_ID, SUPPORTED_ANTHROPIC_MODEL_IDS } from "./model-
 // The provider id and the curated ID lists live in the dependency-free
 // `model-ids.js` leaf, shared with the launch seams (#128); this file is the only
 // one that loads the upstream catalog to turn them into registry rows.
-export { CORTEX_MODEL_PREFIX, CURATED_ANCHOR_MODEL_ID, PROVIDER_ID, SUPPORTED_ANTHROPIC_MODEL_IDS, SUPPORTED_CORTEX_MODEL_IDS, } from "./model-ids.js";
+export { CORTEX_MODEL_PREFIX, CURATED_ANCHOR_MODEL_ID, LEGACY_CORTEX_MODEL_IDS, PROVIDER_ID, SUPPORTED_ANTHROPIC_MODEL_IDS, } from "./model-ids.js";
 // #26 auth-boundary sentinel. `pi.registerProvider` requires an apiKey when a
 // provider defines custom models, but the ACP plugin consumes NO key: backend
 // auth belongs to the operator's own Claude CLI child process (AGENTS
@@ -70,54 +64,44 @@ function requireRegistryModel(models, id) {
 function claudeContextWindow(model) {
     return Math.min(model.contextWindow, CLAUDE_CONTEXT_DEFAULT);
 }
-// ── Cortex (Snowflake Cortex Code) curated surface ──────────────────────────
-//
-// entwurf's ACP rail is backend-extensible: Cortex is the first NON-claude
-// backend to land through it (docs/acp-backend-rail.md, “Shipped adapters”). pi-ai carries no
-// snowflake/cortex model source, so this surface is HAND-CURATED. Every id
-// carries the reserved `cortex-` prefix: the prefix is the SINGLE routing
-// authority (backend-adapter.ts `routeModel`) and keeps the ids off the Claude
-// native ids Cortex routes to (`cortex-claude-sonnet-5` vs the unprefixed
-// `claude-sonnet-5-5` the claude adapter owns). `routeModel` strips the prefix to
-// recover the native id, which is enforced per-turn via
-// session/set_config_option — never a launch `-m` pin (CP0-M).
-//
-// The 4-row set is the GLG-decided curation (2026-07-29) — a subset of the 11
-// native ids cortex v1.1.52 exposed live when authenticated. A curated id that
-// the running cortex no longer serves fails LOUD at set-model, before the
-// prompt (measured: `Unsupported model: …` names the live set). Adding an id
-// here is the same verify-both-axes commitment as the Claude set — do not
-// extend casually. The prefix and the four ids are declared in model-ids.js.
-// Hand-set conservative context window. Cortex reports the LIVE window via its
-// own ACP session config, not this curated metadata — this is a floor for the
-// registry surface, deliberately not inflated to the Claude 1M.
-const CORTEX_CONTEXT_DEFAULT = 200_000;
+// Cortex ACP is disabled; its former IDs are refusal inputs, not model rows.
 /**
- * The curated Cortex model rows handed to the single `entwurf` provider via
- * `allCuratedModels()`. The two Claude rows ride their OWN registry base
- * (opus-5 / sonnet-5); `auto` (default family Claude) and the GPT row (no pi-ai
- * source) ride the sonnet-5 base as a metadata floor. id / name / contextWindow
- * are overridden; the `cortex-` prefix keeps them from colliding with the
- * Claude curated ids. Same row shape as `curatedClaudeModels()` (AcpModelRow).
+ * What an ACP row declares it can take as input: text only. The rail delivers pi's transcript as
+ * ACP text blocks; an image becomes the marker `[image omitted: <mime>]` (`context.ts`), and no
+ * other path carries image bytes to the backend. pi's catalog lists the Anthropic models as
+ * `["text", "image"]` — true of the model behind the API, not of this transport — so copying it
+ * would advertise a capability the rail does not deliver (#142 landing review). A backend gains
+ * `image` here only together with a real image path and its proof.
  */
+const ACP_ROW_INPUT = ["text"];
+/** The retired Cortex adapter contributes no supported model rows. */
 export function curatedCortexModels() {
-    const sonnetBase = requireRegistryModel(ANTHROPIC_MODELS_ALL, "claude-sonnet-5");
-    const opusBase = requireRegistryModel(ANTHROPIC_MODELS_ALL, "claude-opus-5");
-    const row = (id, name, base) => ({
-        id,
-        name,
-        reasoning: base.reasoning,
-        input: base.input,
-        cost: base.cost,
-        contextWindow: CORTEX_CONTEXT_DEFAULT,
-        maxTokens: base.maxTokens,
-    });
-    return [
-        row("cortex-auto", "Cortex · Auto", sonnetBase),
-        row("cortex-claude-opus-5", "Cortex · Claude Opus 5", opusBase),
-        row("cortex-claude-sonnet-5", "Cortex · Claude Sonnet 5", sonnetBase),
-        row("cortex-openai-gpt-5.4", "Cortex · OpenAI GPT-5.4", sonnetBase),
-    ];
+    return [];
+}
+/**
+ * The effort values claude-agent-acp offers on its `effort` config option (category
+ * `thought_level`). `[측정 2026-11-13]` 0.106.0, authenticated, no prompt (#142): the option lists
+ * `default, low, medium, high, xhigh, max`; `high → low → max` each read back on one live session and
+ * `minimal` was refused `-32602`. `default` is the vendor's own choice, so no pi level maps to it.
+ */
+export const CLAUDE_ACP_EFFORT_VALUES = ["low", "medium", "high", "xhigh", "max"];
+/**
+ * The pi `thinkingLevelMap` an ACP Claude row registers (#142). pi's documented model seam: the
+ * value is what the provider sends for each pi level, `null` marks a level unsupported, and xhigh/max
+ * appear only when mapped (`getSupportedThinkingLevels`). Each supported pi level maps to the effort
+ * value of the same name. `off` and `minimal` have no effort value, so they are `null` and never
+ * offered; a level the registry already marks unsupported for this model stays unsupported, and
+ * xhigh/max stay hidden where the registry does not map them. Nothing here is a model catalog: the
+ * registry decides which levels the model has, this decides which of them ACP can carry.
+ */
+export function claudeAcpThinkingLevelMap(registry) {
+    const map = { off: null, minimal: null };
+    for (const level of CLAUDE_ACP_EFFORT_VALUES) {
+        const declared = registry?.[level];
+        const unmapped = declared === undefined && (level === "xhigh" || level === "max");
+        map[level] = declared === null || unmapped ? null : level;
+    }
+    return map;
 }
 /**
  * The curated Claude model rows handed to `pi.registerProvider({ models })`.
@@ -130,7 +114,8 @@ export function curatedClaudeModels() {
         id: m.id,
         name: m.name,
         reasoning: m.reasoning,
-        input: m.input,
+        thinkingLevelMap: claudeAcpThinkingLevelMap(m.thinkingLevelMap),
+        input: [...ACP_ROW_INPUT],
         cost: m.cost,
         contextWindow: claudeContextWindow(m),
         maxTokens: m.maxTokens,

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/tool-surface.js

@@ -12,13 +12,10 @@
 //
 // The module's TWO jobs have different backend scopes — do not collapse them:
 //   - `buildClaudeSessionMeta` is claude-only by CONSTRUCTION, with exactly one
-//     caller (`claudeAdapter.buildSessionMeta`). Cortex exposes no
-//     `_meta.systemPrompt` and no tools/permission declaration surface (native
-//     tools + its own overlay mcp.json projection), so its adapter returns
-//     `undefined` and that function is never reached for a cortex turn.
+//     caller (`claudeAdapter.buildSessionMeta`).
 //   - `assertExcludeToolsHonored` is BACKEND-INVARIANT: backend.ts runs it for
-//     every adapter before any spawn, passing `backend: adapter.backend` and the
-//     resolved `config.tools`. A cortex turn DOES enter this module through it.
+//     every admitted adapter before any spawn, passing `backend: adapter.backend`
+//     and the resolved `config.tools`. Cortex ACP is disabled.
 // That split is why the `backend` field exists: the honest-divergence logic stays
 // explicit and the matrix gate can exercise both the "claude narrows via tools"
 // and "native always exposes" branches.
@@ -104,6 +101,28 @@ export function assertExcludeToolsHonored(activeToolNames, resolved) {
             ". Extension tools (entwurf_v2, entwurf_peers) can be excluded freely — they are pi-side and never reach the backend.");
     }
 }
+/**
+ * #163: is this Pi's own summarization request — the one tool-less turn the preflight above
+ * honours instead of refusing?
+ *
+ * Pi summarizes for `/compact`, the compaction threshold, overflow recovery and `/tree` branch
+ * summaries through one call (pi-coding-agent 1.5.2 `dist/core/compaction/compaction.js:476-489`,
+ * `completeSummarization`; branch summaries at `compaction/branch-summarization.js:233-237`). Its
+ * context declares no tools (`buildSummarizationContext`, `compaction.js:499-509`) and its options
+ * carry `cacheRetention: "none"` (`compaction.js:482`), which an ordinary agent-loop turn does not
+ * (pi-agent-core `dist/agent.js:306-330`).
+ *
+ * BOTH are required. An empty surface alone is also an operator who excluded every tool on an
+ * ordinary turn, which keeps today's refusal; `cacheRetention` alone is a request option, not a
+ * surface. Neither the summarization prompt's text nor a missing session id is read: Pi fills the
+ * id with a fresh `uuidv7()` (`compaction.js:481`), and matching its prompt would copy it.
+ * `cacheRetention` is a Pi convention, not a contract — the oracle beside this calls Pi's own
+ * `completeSummarization` so a Pi upgrade that drops it turns that test red rather than this
+ * path silently back into a refusal.
+ */
+export function isPiSummaryRequest(activeToolNames, cacheRetention) {
+    return activeToolNames.length === 0 && cacheRetention === "none";
+}
 /**
  * Build the `_meta` object handed to `newSession` for a Claude ACP session.
  *
@@ -144,6 +163,14 @@ export function buildClaudeSessionMeta(params, normalizedSystemPrompt) {
             // the carrier's "doesn't-know" — keeping both means a future preset/SDK
             // change cannot silently re-open memory through a channel the strip misses.
             autoMemoryEnabled: false,
+            // No turn of the adapter's own (#142). claude-agent-acp 0.101.0 compacts an idle session
+            // before its 1h prompt cache expires by sending `/compact` as a prompt nobody here issued;
+            // a retained session's callbacks drop updates that arrive with no active turn, so that
+            // model turn would spend quota and replace context invisibly to pi. 0.106.0 (#1555) reads
+            // this inline key when no managed tier sets one. Only the IDLE trigger is off:
+            // `autoCompactEnabled` stays untouched, so Claude Code's own compaction inside a prompt
+            // we sent keeps working.
+            idleCompaction: false,
         },
     };
     if (params.skillPlugins.length > 0) {

package/mcp/entwurf-bridge/dist/pi-extensions/lib/fresh-call-composition.js

@@ -22,6 +22,7 @@
  * (#116 D1), and its two-step launch breaks the ordering argument outright.
  */
 import { randomBytes } from "node:crypto";
+import { PROVIDER_ID, SUPPORTED_ANTHROPIC_MODEL_IDS } from "./acp/model-ids.js";
 /** The backends this rail can open. Fixed set, not a profile — a further one is a decision,
  * not a config entry. `copilot` was added by #82 RAIL 9, `omp` by #87 Bundle C, `codex`
  * by #95 after its system birth and app-server rails were measured, and `pi-durable` by #129
@@ -142,6 +143,35 @@ export const FRESH_CALL_TOOL_LOAD_HINT = {
     codex: [],
     "pi-durable": [],
 };
+/**
+ * Which dialect table spells the bridge tools for THIS launch. The backend picks the runtime; the
+ * model can pick a different tool surface underneath it.
+ *
+ * `[측정 2026-11-13, D1]` a pi sibling opened on an ACP Claude model (`entwurf/claude-*`) does not
+ * see Pi's MCP names: its turns run inside the Claude Agent SDK, which mints the bridge tools as
+ * `mcp__entwurf-bridge__*` (the ACP Sonnet interview of 2026-11-13, n=1, called them by the schema
+ * it was given, not by the pi spelling its framing named). So the NAMES follow the claude-code
+ * table. The load hint stays the pi row (none): in that n=1 the bridge tools were directly callable
+ * without loading. Whether ToolSearch exists on this surface, or deferral can occur with more
+ * declared servers (`acp/tool-surface.ts` names the SDK's deferred tools), is unmeasured — not a
+ * claim that it cannot.
+ *
+ * Only an exact curated Anthropic id switches. A thinking suffix (`:high`) or fuzzy alias never
+ * reaches here through the public verb: the dispatch root refuses any `entwurf/` id that is not
+ * exactly curated (`isUncuratedEntwurfPiModel`, #128), and the test pins that alignment. Retired
+ * Cortex ids are refused at the dispatch root before framing. The ACP id list arrives from
+ * `acp/model-ids.js`, an import-free module.
+ */
+export function freshCallToolDialect(backend, model) {
+    if (backend !== "pi")
+        return backend;
+    const trimmed = model.trim();
+    const slash = trimmed.indexOf("/");
+    if (slash < 0 || trimmed.slice(0, slash) !== PROVIDER_ID)
+        return backend;
+    const id = trimmed.slice(slash + 1);
+    return SUPPORTED_ANTHROPIC_MODEL_IDS.includes(id) ? "claude-code" : backend;
+}
 /**
  * The omp bootstrap flag, spelled WITHOUT dashes — the vendor's flag map is keyed by bare
  * name (`extensions/loader.ts:221-228`) and this composition adds the `--` itself.
@@ -379,9 +409,10 @@ export function composeBackendArgs(backend, composition, model, resolveCodexSock
  * corroborate the caller instead of an instruction not to look.
  */
 export function composeFreshCallFraming(params) {
-    const birthTool = FRESH_CALL_CALLBACK_TOOL[params.backend];
-    const deliveryTool = FRESH_CALL_DELIVERY_TOOL[params.backend];
-    const peersTool = FRESH_CALL_PEERS_TOOL[params.backend];
+    const dialect = freshCallToolDialect(params.backend, params.model);
+    const birthTool = FRESH_CALL_CALLBACK_TOOL[dialect];
+    const deliveryTool = FRESH_CALL_DELIVERY_TOOL[dialect];
+    const peersTool = FRESH_CALL_PEERS_TOOL[dialect];
     // The hint is a per-backend TEMPLATE so the two tool dialects stay the single source of their
     // own spelling here too — a hint that hard-coded Claude's name would go stale the day a dialect
     // moves, and it would go stale silently, in the one sentence a stuck child depends on.

package/mcp/entwurf-bridge/dist/pi-extensions/lib/herdr-fresh-call.js

@@ -554,6 +554,7 @@ export async function herdrFreshCall(params, run, env, nonce, clock = HERDR_REAL
         return { ok: false, reason: badCwd };
     const framing = composeFreshCallFraming({
         backend,
+        model,
         callerGardenId,
         nonce,
         openingLine: HERDR_FRESH_CALL_OPENING_LINE,
@@ -1220,6 +1221,7 @@ async function herdrLayoutFreshCall(params, context, env, nonce, deps) {
         return { ok: false, reason: "herdr-socket-path-missing" };
     const prompt = composeFreshCallPrompt({
         backend: "pi-durable",
+        model,
         task,
         callerGardenId,
         nonce,
@@ -1287,7 +1289,7 @@ export const HERDR_REJECT_HINT = {
     "model-invalid": "the model is not in the accepted grammar (no whitespace, no leading dash)",
     // #128: decided at the dispatch root (`fresh-call-dispatch.ts`), worded here because this rail's
     // import fence admits no ACP module. The curated list itself lives in `acp/model-ids.js`.
-    "acp-model-not-curated": "an entwurf model must be one exact curated ACP id — Pi would otherwise pick another row by substring (a retired claude-sonnet-5 lands on cortex-claude-sonnet-5), so nothing was opened and nothing was aliased",
+    "acp-model-not-curated": "an entwurf model must be one exact curated ACP id; Cortex ACP is disabled. Pi may otherwise pick another row by substring, so nothing was opened or aliased",
     "task-empty": "a sibling opened with nothing to do is a window nobody asked for",
     "task-too-long": `the task is over the ${TASK_MAX_CHARS}-character interface bound this verb shares with entwurf_v2`,
     "herdr-context-missing": "HERDR_ENV/HERDR_BIN_PATH are absent, so this process is not inside herdr and this rail does not exist here",

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-fresh-call.js

@@ -331,7 +331,7 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
         const runtime = layout === null ? null : checkPiDurableRuntime(layout);
         const missing = piDurableFreshPreflight({
             model,
-            firstInput: buildFreshCallPrompt({ backend: params.backend, task, callerGardenId, nonce }),
+            firstInput: buildFreshCallPrompt({ backend: params.backend, model, task, callerGardenId, nonce }),
             layout,
             runtime: runtime === null || runtime.ok ? null : runtime.reason,
         });
@@ -373,6 +373,7 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
     const composition = {
         prompt: buildFreshCallPrompt({
             backend: params.backend,
+            model,
             task,
             callerGardenId,
             nonce,

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.52.0",
-	"description": "Visible sibling sessions across independent agent harnesses: launch in Herdr or tmux, retire on request, visibly reopen supported sessions under the same id, and deliver messages by garden id; native bridges and Claude/Cortex ACP adapters.",
+	"version": "0.53.1",
+	"description": "Visible sibling sessions across independent agent harnesses: launch in Herdr or tmux, retire on request, visibly reopen supported sessions under the same id, and deliver messages by garden id; native bridges and a Claude ACP adapter.",
 	"license": "MIT",
 	"author": {
 		"name": "Junghan Kim",
@@ -102,8 +102,8 @@
 		"claudeCodeFloor": ">=2.1.306"
 	},
 	"dependencies": {
-		"@agentclientprotocol/claude-agent-acp": "0.90.0",
-		"@agentclientprotocol/sdk": "1.8.0",
+		"@agentclientprotocol/claude-agent-acp": "0.107.0",
+		"@agentclientprotocol/sdk": "2.6.0",
 		"@anthropic-ai/sdk": "0.100.1",
 		"@earendil-works/chord": "1.5.2",
 		"@earendil-works/pi-agent-core": "1.5.2",

package/pi/settings.reference.json

@@ -32,7 +32,6 @@
 			"WebFetch",
 			"WebSearch"
 		],
-		"cortexConnection": "MY_SNOWFLAKE_CONNECTION",
 		"mcpServers": {
 			"entwurf-bridge": {
 				"command": "/path/to/entwurf/mcp/entwurf-bridge/start.sh",

package/pi-extensions/acp-provider.ts

@@ -3,9 +3,8 @@
 // This is the pi-extension entry point that registers `entwurf` as a pi
 // session provider/model. It is intentionally THIN: it stands up the provider
 // surface (every registered adapter's curated rows + the no-auth sentinel) and
-// wires streamSimple to the real ACP backend (lib/acp/backend.ts — a
-// spawn-per-turn ACP child, `claude-agent-acp` or `cortex acp serve` depending
-// on which adapter the model id routes to). It does NOT build a
+// wires streamSimple to the real ACP backend (lib/acp/backend.ts — a Claude
+// ACP child whose lifetime follows pi's lifecycle). It does NOT build a
 // socket/peers/citizen protocol or touch the v2 core — socket-citizenship is
 // supplied by the host `--entwurf-control` pi session (AGENTS §ACP Plugin
 // Boundary).
@@ -13,8 +12,8 @@
 // The model set comes from `allCuratedModels()` — the union across the adapter
 // registry (backend-adapter.ts), NOT a per-backend list spelled here. Adding a
 // backend therefore never edits this file. check-acp-provider-surface pins that
-// the compiled entry really registers the EXACT union
-// ([QK:CORTEX-PROVIDER-EXACT-ROW-SURFACE]).
+// the compiled entry registers the exact supported Claude-only set
+// ([QK:ACP-PROVIDER-CLAUDE-ONLY]).
 //
 // Fence: this entry rides the emit-capable root tsconfig (it is not in the root
 // `exclude` list); its lib modules are imported with `.js` suffixes (the root
@@ -22,7 +21,7 @@
 // strip-types fence is introduced.
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { streamShellAcp } from "./lib/acp/backend.js";
+import { closeRetainedAcpSession, streamShellAcp } from "./lib/acp/backend.js";
 import { allCuratedModels } from "./lib/acp/backend-adapter.js";
 import { ENTWURF_ACP_NO_AUTH_SENTINEL, PROVIDER_ID } from "./lib/acp/models.js";
 
@@ -65,6 +64,13 @@ export default function (pi: ExtensionAPI) {
 		streamSimple: streamShellAcp,
 	});
 
+	// #163, GLG 2026-11-14: a successful compaction closes the Claude child of this Pi session at
+	// once. The next turn opens a new child from the compacted transcript (backend.ts
+	// `closeRetainedAcpSession`). A session that never used an ACP model has nothing to close.
+	pi.on("session_compact", (_event, ctx) => {
+		closeRetainedAcpSession(ctx.sessionManager.getSessionId());
+	});
+
 	// Mark only AFTER a successful registration. If allCuratedModels() (which
 	// fail-fasts on an unowned/duplicate curated id, and whose claude rows carry a
 	// fail-loud anchor check) or registerProvider throws, the runtime is not left

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

@@ -17,13 +17,12 @@
 // smokes both drive ONE adapter — the SDK method-name mapping lives here only,
 // and the backend's orchestration + the gate fakes stay untouched.
 
-import {
-	type Usage as AcpWireUsage,
-	AGENT_METHODS,
-	CLIENT_METHODS,
-	client,
-	type Stream,
-} from "@agentclientprotocol/sdk";
+import { AGENT_METHODS, CLIENT_METHODS, client, type Stream } from "@agentclientprotocol/sdk";
+// SDK 2.x moved the experimental `Usage` out of the stable root into the `./unstable`
+// entry (`dist/v1/unstable/schema/types.gen.d.ts`, marked UNSTABLE/@experimental). A
+// type-only import: nothing of it reaches the emitted JS, and the wire carries the
+// same `usage` object either way.
+import type { Usage as AcpWireUsage } from "@agentclientprotocol/sdk/unstable";
 import type { AcpTextBlock } from "./context.js";
 
 /**

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

@@ -27,11 +27,12 @@ import type { AcpConnectionLike } from "./acp-client.js";
 import { enrichMcpServersWithEnvelope, type ResolvedAcpConfig } from "./config.js";
 import { loadEngraving } from "./engraving.js";
 import {
+	CLAUDE_ACP_EFFORT_VALUES,
 	CORTEX_MODEL_PREFIX,
 	curatedClaudeModels,
 	curatedCortexModels,
+	LEGACY_CORTEX_MODEL_IDS,
 	SUPPORTED_ANTHROPIC_MODEL_IDS,
-	SUPPORTED_CORTEX_MODEL_IDS,
 } from "./models.js";
 import { claudeLaunchEnvDefaults, ensureClaudeConfigOverlay, ensureCortexDualHomeOverlay } from "./overlay.js";
 import { buildClaudeSessionMeta } from "./tool-surface.js";
@@ -57,7 +58,10 @@ export interface AcpLaunchSpec {
 }
 
 /** A curated provider model row (the shape pi.registerProvider({ models }) takes). */
-export type AcpModelRow = ReturnType<typeof curatedClaudeModels>[number];
+/** `thinkingLevelMap` is optional: Claude rows declare the effort levels its driver can set (#142);
+ *  cortex rows declare none and keep pi's default thinking handling. */
+type ClaudeModelRow = ReturnType<typeof curatedClaudeModels>[number];
+export type AcpModelRow = Omit<ClaudeModelRow, "thinkingLevelMap"> & Partial<Pick<ClaudeModelRow, "thinkingLevelMap">>;
 
 /** routeModel result — the backend-native model id with the curation prefix stripped. */
 export interface AcpRoutedModel {
@@ -112,6 +116,23 @@ export interface AcpEnforceModelParams {
 	nativeModelId: string;
 }
 
+/** resolveThinking input — pi's requested level and the registered row's level map. `reasoning`
+ *  is `undefined` both when the pi thinking level is `off` and when none was given: pi-agent-core
+ *  sends `thinkingLevel === "off" ? undefined : level`, so the provider cannot tell them apart. */
+export interface AcpResolveThinkingParams {
+	modelId: string;
+	reasoning: string | undefined;
+	thinkingLevelMap: Readonly<Record<string, string | null | undefined>> | undefined;
+}
+
+/** enforceThinking input — the live connection + acp session + the resolved backend value. */
+export interface AcpEnforceThinkingParams {
+	connection: AcpConnectionLike;
+	acpSessionId: string;
+	modelId: string;
+	value: string;
+}
+
 /** ensureOverlay result — env overrides backend.ts merges into the spawn env. */
 export interface AcpOverlayResult {
 	envOverrides: Record<string, string>;
@@ -211,6 +232,15 @@ export interface AcpBackendAdapter {
 	 *  launch-pinned backend: no-op here). backend.ts wraps the call in withTimeout. */
 	enforceModel(params: AcpEnforceModelParams): Promise<void>;
 
+	/** OPTIONAL capability (#142): carry pi's thinking level to the backend. Both or neither.
+	 *  `resolveThinking` is PURE — it maps the requested level to the backend value through the
+	 *  registered row's `thinkingLevelMap` and throws a named refusal when there is none, before
+	 *  any process or session is touched. `enforceThinking` sets that value on the live session
+	 *  and refuses unless the answer reads it back. ABSENT (cortex) keeps the old behaviour: the
+	 *  level is not carried, and nothing claims it is. */
+	resolveThinking?(params: AcpResolveThinkingParams): string;
+	enforceThinking?(params: AcpEnforceThinkingParams): 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
@@ -345,7 +375,7 @@ export const CLAUDE_FOREGROUND_ONLY_ENV = { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS
  * The set-model answer is read back before the prompt (#128). claude-agent-acp resolves the
  * requested id onto one of the rows it offers and answers with that row's `value` as the model
  * option's `currentValue` (0.85.1 `dist/acp-agent.js:5459-5499`). `[측정 2026-10-12]` 0.85.1, no
- * prompt: `claude-fable-5-1` answers its own row, while `claude-sonnet-5-5` and `claude-opus-5-5`
+ * prompt: `claude-fable-5-1` answers its own row (and, at 0.106.0 #142, so does `claude-fable-5-2`), while `claude-sonnet-5-5` and `claude-opus-5-5`
  * answer the alias rows `sonnet` and `opus`, named `Sonnet 5.5` and `Opus 5.5`. The id an alias row
  * resolves to (`ModelInfo.resolvedModel`) is not on the ACP wire, so an alias answer is accepted
  * only as the exact measured row, value AND name, declared here for the requested id. No other
@@ -385,6 +415,61 @@ export function confirmClaudeSetModelAnswer(response: unknown, nativeModelId: st
 	);
 }
 
+const CLAUDE_EFFORT_VALUE_SET: ReadonlySet<string> = new Set(CLAUDE_ACP_EFFORT_VALUES);
+
+/** The named refusal for a thinking level ACP Claude cannot carry (#142). The text is fixed and
+ *  must read as NON-transient to pi's retry and overflow classifiers: replaying the turn cannot
+ *  change the level that was asked for. */
+export const ACP_THINKING_LEVEL_UNSUPPORTED = "acp-thinking-level-unsupported";
+
+/**
+ * Map pi's requested level to the claude-agent-acp effort value, or refuse by name (#142).
+ * The value is the registered row's `thinkingLevelMap` entry for that level — the documented pi
+ * meaning of the map — and must be one of the measured effort values. `undefined` (pi off, or no
+ * level) is refused rather than left at the vendor `default`: that would let the turn run at a
+ * depth nobody chose while the operator believes a level was applied.
+ */
+export function resolveClaudeEffort(
+	modelId: string,
+	reasoning: string | undefined,
+	thinkingLevelMap: Readonly<Record<string, string | null | undefined>> | undefined,
+): string {
+	const value = reasoning === undefined ? undefined : thinkingLevelMap?.[reasoning];
+	if (typeof value === "string" && CLAUDE_EFFORT_VALUE_SET.has(value)) return value;
+	const asked =
+		reasoning === undefined
+			? "no thinking level (pi sends none for `off`, and none when no level is set; the two are indistinguishable here)"
+			: `thinking level ${JSON.stringify(reasoning)}`;
+	throw new Error(
+		`entwurf: ${ACP_THINKING_LEVEL_UNSUPPORTED} — ${modelId} over Claude ACP carries effort ` +
+			`${CLAUDE_ACP_EFFORT_VALUES.join("/")} only, and was asked for ${asked}. Choose one of those levels; ` +
+			`the turn was not sent, and repeating it at the same level cannot change that.`,
+	);
+}
+
+function claudeEffortRefusal(modelId: string, value: string, what: string, cause?: unknown): Error {
+	const error = new Error(
+		`entwurf: claude-agent-acp ${what} for effort ${JSON.stringify(value)} on ${modelId}. Refusing before the prompt ` +
+			`so the turn cannot run at an effort nobody chose; repeating the turn cannot change the driver's answer.`,
+	);
+	if (cause !== undefined) (error as Error & { cause?: unknown }).cause = cause;
+	return error;
+}
+
+/** Refuse unless the set-effort answer reads back the requested value. */
+export function confirmClaudeEffortAnswer(response: unknown, modelId: string, value: string): void {
+	const configOptions = (response as { configOptions?: unknown } | null | undefined)?.configOptions;
+	const effort = Array.isArray(configOptions)
+		? (configOptions as Array<Record<string, unknown> | null>).find((option) => option?.id === "effort")
+		: undefined;
+	if (effort?.currentValue === value) return;
+	throw claudeEffortRefusal(
+		modelId,
+		value,
+		effort == null ? "answered with no effort option" : `answered effort ${jsonText(effort.currentValue)}`,
+	);
+}
+
 export const claudeAdapter: AcpBackendAdapter = {
 	backend: "claude",
 
@@ -456,6 +541,24 @@ export const claudeAdapter: AcpBackendAdapter = {
 		confirmClaudeSetModelAnswer(answer, nativeModelId);
 	},
 
+	resolveThinking({ modelId, reasoning, thinkingLevelMap }) {
+		return resolveClaudeEffort(modelId, reasoning, thinkingLevelMap);
+	},
+
+	async enforceThinking({ connection, acpSessionId, modelId, value }) {
+		const setConfig = connection.setSessionConfigOption;
+		if (typeof setConfig !== "function") {
+			throw new Error(`setSessionConfigOption unsupported — cannot set effort for ${modelId}`);
+		}
+		let answer: unknown;
+		try {
+			answer = await setConfig.call(connection, { sessionId: acpSessionId, configId: "effort", value });
+		} catch (err) {
+			throw claudeEffortRefusal(modelId, value, "refused the set", err);
+		}
+		confirmClaudeEffortAnswer(answer, modelId, value);
+	},
+
 	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
@@ -480,17 +583,11 @@ export const claudeAdapter: AcpBackendAdapter = {
 // Registry — modelId → adapter
 // ---------------------------------------------------------------------------
 
-/** Registered adapters. Order carries NO routing authority — routeModel decides.
- *  claude (unprefixed ids) + cortex (the `cortex-` prefix). A further backend
- *  appends here with its own reserved prefix; the fail-fast below proves no two
- *  adapters claim one id. */
-// ---------------------------------------------------------------------------
-// cortex adapter — Snowflake Cortex Code, the first non-claude backend on the
-// rail (docs/acp-backend-rail.md, “Shipped adapters”). It adds ZERO to the common layer:
-// everything cortex-specific lives here + models.ts + overlay.ts + the gates.
-// ---------------------------------------------------------------------------
+// The former Cortex implementation is retained privately for historical source
+// continuity only. The exported adapter below denies every side-effecting entry,
+// and the production registry does not contain this implementation.
 
-const SUPPORTED_CORTEX_IDS: ReadonlySet<string> = new Set(SUPPORTED_CORTEX_MODEL_IDS);
+const SUPPORTED_CORTEX_IDS: ReadonlySet<string> = new Set(LEGACY_CORTEX_MODEL_IDS);
 
 /** Cortex's OWN settings: a Snowflake connection name, or null. Opaque to
  *  config.ts / backend.ts — only cortexAdapter reads it (casting back). */
@@ -503,7 +600,7 @@ export interface CortexAdapterSettings {
  *  ENTWURF_ACP_* convention (PR #40's legacy PI_SHELL_ACP* cortex-connection var renamed). */
 export const CORTEX_CONNECTION_ENV = "ENTWURF_ACP_CORTEX_CONNECTION";
 
-export const cortexAdapter: AcpBackendAdapter = {
+const retiredCortexAdapter: AcpBackendAdapter = {
 	backend: "cortex",
 
 	// Cortex owns the reserved `cortex-` prefix (rail “Adapter contract”). routeModel strips it to the
@@ -649,7 +746,31 @@ export const cortexAdapter: AcpBackendAdapter = {
 	// errorMessage. Borrowing claude's `incomplete_tool_call` reader would be a guess.
 };
 
-const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter, cortexAdapter];
+const cortexDisabled = (): never => {
+	throw new Error("entwurf: cortex-acp-disabled: Cortex ACP is not supported");
+};
+
+/** Retained exported shape refuses the retired adapter before a launch or overlay can be made. */
+export const cortexAdapter: AcpBackendAdapter = {
+	...retiredCortexAdapter,
+	routeModel: () => undefined,
+	curatedModels: () => [],
+	resolveAdapterSettings: cortexDisabled,
+	resolveLaunch: cortexDisabled,
+	launchEnvDefaults: cortexDisabled,
+	ensureOverlay: cortexDisabled,
+	loadCarrier: cortexDisabled,
+	buildSessionMeta: cortexDisabled,
+	enforceModel: cortexDisabled,
+	configSignatureFields: cortexDisabled,
+};
+
+const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter];
+
+/** A declared backend is only a guard, never a replacement routing authority. */
+export function assertSupportedDeclaredBackend(backend: string | undefined): void {
+	if (backend?.toLowerCase() === "cortex") cortexDisabled();
+}
 
 /**
  * Resolve the backend adapter that owns `modelId`.
@@ -662,6 +783,9 @@ const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter, cortexAdapter];
  * so callers get `{ adapter, nativeModelId }` and never re-parse the id string.
  */
 export function resolveAcpBackendAdapter(modelId: string): { adapter: AcpBackendAdapter; nativeModelId: string } {
+	if (modelId.toLowerCase().startsWith(CORTEX_MODEL_PREFIX)) {
+		throw new Error(`entwurf: cortex-acp-disabled: ${JSON.stringify(modelId)} is not supported`);
+	}
 	const matches: Array<{ adapter: AcpBackendAdapter; nativeModelId: string }> = [];
 	for (const adapter of ADAPTERS) {
 		const routed = adapter.routeModel(modelId);