@junghanacs/entwurf 0.12.6 → 0.12.7

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

@@ -0,0 +1,105 @@
+// ACP plugin — billing carrier (engraving) loader (S2d-1c).
+//
+// The engraving is the OPERATOR surface for the Claude `_meta.systemPrompt`
+// carrier — short, personal additions an operator wants attached to every ACP
+// session's system prompt. It is NOT the bridge-identity / AGENTS / pi-base
+// narrative: that rich context rides the first-user-message augment (augment.ts)
+// because the system-prompt carrier MUST stay tiny.
+//
+// Why a SMALL but NON-EMPTY default (the v1 memory-containment lever, restored):
+// shipping a non-empty string here makes claude-agent-acp REPLACE its
+// `claude_code` preset with this string (acp-agent.js: string-form
+// `_meta.systemPrompt` → full preset replacement). That replacement strips the
+// preset's auto-memory section, so the ACP model never learns it has a per-session
+// memory store — the containment the operator baseline depends on. An EMPTY
+// carrier keeps the preset and re-leaks auto-memory (the model writes memory/*.md
+// via Write): that regression is exactly what a non-empty default fixes.
+//
+// Billing axis is SIZE, not SHAPE (NEXT §S2-scout 핀1, oracle A): Anthropic
+// subscription billing (Claude Code OAuth, 정액제) reclassifies a call as metered
+// "extra usage" — HTTP 400 for users with no metered balance — when the carrier
+// materially GROWS past the SDK-default size (e.g. by injecting AGENTS.md or the
+// pi base prompt). A tiny placeholder string is shape-deviant yet v1-production-
+// safe, so the rule is keep the carrier SHORT, never "absent". Rich context still
+// rides the first-user-message augment (augment.ts), never this carrier.
+//
+// Stability contract (NEXT oracle C / 핀1): the rendered output MUST be a pure
+// function of (template content on disk, backend, mcpServerNames). No clock /
+// random / env-time. `bridgeConfigSignature` folds this string into its
+// `appendSystemPrompt` slot — if the rendered carrier drifted turn-to-turn, the
+// signature would drift and entwurf would rebuild the ACP session every
+// turn. The default-path source is cached once for exactly this reason, so a
+// resident's carrier never drifts mid-session. The env-override path instead
+// re-reads on EVERY call: editing that file mid-session INTENTIONALLY drifts the
+// rendered carrier → bridgeConfigSignature changes → the live session is judged
+// incompatible and the next turn opens a fresh ACP session with the new carrier.
+// That per-turn rebuild is the accepted cost of the A/B opt-in surface, never the
+// shipped default (which stays cached precisely so a resident never rebuilds).
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ENGRAVING_PATH = join(HERE, "prompts", "engraving.md");
+let cached = null;
+/** Point the loader at an alternate engraving file (A/B); bypasses the cache. */
+function resolveEngravingPath() {
+    const envPath = process.env.ENTWURF_ACP_ENGRAVING_PATH?.trim();
+    return envPath ? resolve(envPath) : DEFAULT_ENGRAVING_PATH;
+}
+function loadSource(filePath) {
+    // Env-override path → always re-read (A/B experimentation). Default path →
+    // cache once so a mid-session operator edit cannot drift the carrier (and thus
+    // bridgeConfigSignature) between turns of a resident.
+    if (filePath !== DEFAULT_ENGRAVING_PATH) {
+        return readFileSync(filePath, "utf8");
+    }
+    if (!cached || cached.filePath !== filePath) {
+        cached = { filePath, content: readFileSync(filePath, "utf8") };
+    }
+    return cached.content;
+}
+function interpolate(template, params) {
+    // Sort so a caller-side ordering difference can never drift the rendered text
+    // (and therefore the config signature) — GPT c32a6c8 determinism guard.
+    const names = [...params.mcpServerNames].sort();
+    const mcpList = names.length > 0 ? names.join(", ") : "(none registered)";
+    return template.replace(/\{\{backend\}\}/g, params.backend).replace(/\{\{mcp_servers\}\}/g, mcpList);
+}
+/**
+ * The rendered engraving carrier, or null when an ENV-OVERRIDE engraving file
+ * (`ENTWURF_ACP_ENGRAVING_PATH`) is empty, whitespace-only, missing, or
+ * unreadable — that null is the operator opt-out. The SHIPPED default, by
+ * contrast, IS the auto-memory containment lever (its non-empty carrier replaces
+ * the claude_code preset, stripping the auto-memory advertisement) and MUST be
+ * present + non-empty: if the shipped default is missing/unpackaged/empty this
+ * THROWS (fail-loud, Detour C) rather than silently shipping with the carrier
+ * strip off. To opt the carrier out, point the env override at an empty file.
+ * Callers MUST treat null as "no carrier configured" and omit `_meta.systemPrompt`
+ * entirely (passing "" as the `appendSystemPrompt` signature input) so
+ * subscription billing is never reclassified.
+ */
+export function loadEngraving(params) {
+    const filePath = resolveEngravingPath();
+    const isShippedDefault = filePath === DEFAULT_ENGRAVING_PATH;
+    let source;
+    try {
+        source = loadSource(filePath);
+    }
+    catch (err) {
+        if (isShippedDefault) {
+            throw new Error(`entwurf: shipped engraving carrier unreadable at ${filePath} — it is the auto-memory ` +
+                `containment lever; refusing to proceed with containment silently degraded. (${err.message})`);
+        }
+        return null;
+    }
+    const rendered = interpolate(source, params).trim();
+    if (rendered.length === 0) {
+        if (isShippedDefault) {
+            throw new Error(`entwurf: shipped engraving carrier at ${filePath} is empty — it is the auto-memory ` +
+                `containment lever; refusing to proceed with the carrier strip silently off. ` +
+                `(opt out via an empty ENTWURF_ACP_ENGRAVING_PATH file instead)`);
+        }
+        return null;
+    }
+    return rendered;
+}

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

@@ -0,0 +1,90 @@
+// ACP plugin — curated Claude model surface (S0 loader/fence slice).
+//
+// 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 Claude anchor the plugin commits to
+// driving through a real ACP backend (the backend lands in S2; S0 only stands
+// the provider/model surface up).
+//
+// Claude-first scope (NEXT §스코프): Codex is already a native garden citizen
+// and Gemini / major tools use native, so the curated surface is Claude-only on
+// this lane. A second governed backend would EXTEND this set — it does not change
+// the pattern.
+// 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.
+//
+// Why `/compat` and NOT the 0.80 provider-factory subpath (the pi-ai
+// providers/anthropic subpath): this file is loaded by pi's
+// EXTENSION loader (pi-coding-agent `core/extensions/loader.ts`), whose jiti
+// alias map resolves ONLY three pi-ai specifiers for extensions — the bare root,
+// `/compat`, and `/oauth` — all to `ai/dist/compat.js`. A `providers/*` subpath
+// is NOT in that map: jiti prefix-matches the bare `@earendil-works/pi-ai` alias
+// and appends the remainder, yielding the unresolvable
+// `…/dist/compat.js/providers/anthropic` (verified live: extension load crash,
+// invisible to static typecheck which resolves against node_modules `exports`).
+// So `/compat` is the SINGLE sanctioned extension entrypoint for the old global
+// model-catalog API, and the SINGLE allowlisted exception in
+// `run.sh check-pi-import-surface`. `getModels` here is compat's deprecated
+// re-export of `getBuiltinModels`. When pi removes compat we migrate to whatever
+// the loader then exposes.
+import { getModels } from "@earendil-works/pi-ai/compat";
+/** Provider id — current pre-rename surface; S1 renames this load-bearing id to `entwurf`. */
+export const PROVIDER_ID = "entwurf";
+// #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
+// §Operating boundaries — trust invariants). This lowercase+hyphen literal
+// satisfies pi's auth-present check WITHOUT being read as an ENV reference. An
+// ALL-CAPS value like "ANTHROPIC_API_KEY" would (a) trip pi's legacy-env
+// deprecation and (b) falsely present the plugin as Anthropic-key dependent,
+// failing preflight when the var is unset. Do NOT change to "$ANTHROPIC_API_KEY"
+// — that silences the warning but keeps the wrong auth-boundary shape. The
+// check-auth-boundary gate pins this.
+export const ENTWURF_ACP_NO_AUTH_SENTINEL = "entwurf-no-auth";
+// The curated Claude ids. Adding one here is a commitment to verify it across
+// both axes (protocol smoke + agent interview) — do not extend casually.
+// Exported so the claude backend adapter (backend-adapter.ts) can answer
+// `routeModel` without re-deriving the set from curatedClaudeModels().
+export const SUPPORTED_ANTHROPIC_MODEL_IDS = ["claude-sonnet-5", "claude-opus-4-8"];
+/** The anchor model whose absence is a hard registry regression, not a soft skip. */
+export const CURATED_ANCHOR_MODEL_ID = "claude-opus-4-8";
+// Anthropic's registry reports 1M for both Sonnet 5 and Opus 4.8, and the
+// entwurf surface now exposes the full 1M for BOTH. Sonnet 5's 1M window is the
+// whole point of the 0.12.3 bump — it is the compact-free long-context floor the
+// earlier 200K Sonnet cap could not provide. We still clamp to a 1M ceiling so a
+// future registry value can't silently inflate the surface past what we verify.
+const CLAUDE_CONTEXT_DEFAULT = 1_000_000;
+// `getModels("anthropic")` reads the static builtin model catalog only — no env
+// read, no credential access, no network — preserving the #26 auth-boundary
+// invariant: the curated surface consumes no key.
+const ANTHROPIC_MODELS_ALL = getModels("anthropic");
+function requireRegistryModel(models, id) {
+    const model = models.find((m) => m.id === id);
+    // Crash, don't warn (AGENTS): a missing anchor is a genuine pi-ai metadata
+    // regression and must fail the curated surface up front rather than be
+    // papered over with a fabricated row.
+    if (!model)
+        throw new Error(`entwurf: required Claude model missing from pi-ai registry: ${id}`);
+    return model;
+}
+function claudeContextWindow(model) {
+    return Math.min(model.contextWindow, CLAUDE_CONTEXT_DEFAULT);
+}
+/**
+ * The curated Claude model rows handed to `pi.registerProvider({ models })`.
+ * Fail-loud if the anchor is absent from the pi-ai registry.
+ */
+export function curatedClaudeModels() {
+    const supported = new Set(SUPPORTED_ANTHROPIC_MODEL_IDS);
+    requireRegistryModel(ANTHROPIC_MODELS_ALL, CURATED_ANCHOR_MODEL_ID);
+    return ANTHROPIC_MODELS_ALL.filter((m) => supported.has(m.id)).map((m) => ({
+        id: m.id,
+        name: m.name,
+        reasoning: m.reasoning,
+        input: m.input,
+        cost: m.cost,
+        contextWindow: claudeContextWindow(m),
+        maxTokens: m.maxTokens,
+    }));
+}

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

@@ -0,0 +1,194 @@
+// ACP plugin — Claude config overlay materializer (S2b).
+//
+// claude-agent-acp's SettingsManager loads the operator's `~/.claude/settings.json`
+// DIRECTLY (CLAUDE_CONFIG_DIR is the only knob that redirects that read). So the
+// operator's native `permissions.defaultMode` ("auto"), hooks, plugins, and
+// per-cwd memory/projects state would otherwise leak into entwurf ACP
+// sessions. The overlay redirects SettingsManager at a pi-owned directory whose
+// `settings.json` WE author (minimal, `hooks:{}`), while keeping exactly the
+// operator entries a backend needs (credentials, caches, built-in skills)
+// reachable through a TIGHT symlink whitelist — nothing else.
+//
+// Scope (NEXT §스코프 / §S2-scout 핀3): Claude-only on this lane. Codex/Gemini
+// overlays (CODEX_HOME / admin.toml) are 0.11.0 behavior-oracle territory and
+// out of scope — the bridge backends are not in v2 yet.
+//
+// Two deliberate divergences from the literal 0.11.0 illustrative comment block
+// (the 0.11.0 CODE already does both — only its top doc-comment drew projects/
+// as a symlink): `projects/` and `sessions/` are overlay-PRIVATE empty dirs, not
+// symlinks, so the operator's real ~/.claude/{projects,sessions} is never read
+// or written from an ACP session (this also closes the per-cwd MEMORY.md
+// auto-load leak: the binary finds an empty tree and injects nothing).
+//
+// `hooks:{}` is load-bearing, not cosmetic: the Claude SDK distinguishes an
+// ABSENT hooks key from a configured-but-empty map during organic compaction
+// (the absent shape made a compacting turn emit a meta summary instead of
+// answering — 0.11.0 LIVE probe). Keeping it `{}` inherits NO operator hook —
+// which is exactly the "mailbox absence by design" the plugin commits to
+// (no meta-bridge hook on this child's settings surface → no mailbox).
+import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Operator's real Claude config dir — the symlink-passthrough SOURCE. */
+export const CLAUDE_REAL_CONFIG_DIR = join(homedir(), ".claude");
+/** pi-owned overlay dir — the CLAUDE_CONFIG_DIR target for ACP child spawns. */
+export const CLAUDE_CONFIG_OVERLAY_DIR = join(homedir(), ".pi", "agent", "claude-config-overlay");
+/**
+ * Operator `~/.claude/` entries exposed to the ACP child via symlink. Anything
+ * NOT here is intentionally hidden: CLAUDE.md, hooks, agents, plugins,
+ * settings.local.json (personal env / PAT), sessions/projects data, command
+ * history, todos — none leak into the model context, hook surface, or env.
+ *
+ * Limited to: backend auth (`.credentials.json`); the binary's runtime caches +
+ * telemetry (cache, debug, session-env, stats-cache.json, statsig, telemetry);
+ * the bridge's own scratch surface (shell-snapshots); and built-in
+ * (non-operator-defined) skill content (skills). `plugins` is deliberately out —
+ * plugin enablement is operator-personal; the plugin set is injected per-session
+ * via `_meta.claudeCode.options.plugins`, not filesystem inheritance.
+ */
+export const OVERLAY_PASSTHROUGH = new Set([
+    ".credentials.json",
+    "cache",
+    "debug",
+    "session-env",
+    "shell-snapshots",
+    "skills",
+    "stats-cache.json",
+    "statsig",
+    "telemetry",
+]);
+/**
+ * Directories owned by the overlay itself (empty trees). The binary
+ * auto-creates and writes per-cwd state under these; an empty overlay-scoped
+ * tree keeps operator data at ~/.claude/{projects,sessions} unread/unwritten.
+ * Memory containment is NOT provided by this directory shape alone: if the
+ * backend preset advertises project memory, Claude can still write overlay-local
+ * projects/<cwd>/memory files. The engraving carrier's tiny non-empty preset
+ * replacement strips that advertisement; the empty tree is read-isolation and
+ * defense-in-depth, not the primary write-containment lever.
+ */
+export const OVERLAY_EMPTY_DIRS = new Set(["projects", "sessions"]);
+/**
+ * Entries the binary creates INSIDE whatever CLAUDE_CONFIG_DIR it is pointed at
+ * (feature cache, `.claude.json` backups). They have no operator-side
+ * counterpart, so the cleanup pass preserves real files/dirs here but tears down
+ * any STALE symlink (a migration artifact from earlier overlay code that linked
+ * every entry). `settings.json` is overlay-authored but listed for symmetry so
+ * the cleanup loop never nukes it.
+ */
+export const OVERLAY_BINARY_OWNED = new Set([".claude.json", "backups", "settings.json"]);
+/**
+ * Minimal overlay settings.json. Only fields with a reason to pin:
+ *   - `permissions.defaultMode: "default"` neutralizes the operator's native
+ *     "auto"; combined with the explicit `tools`/`permissionAllow` surface,
+ *     "default" auto-passes every tool we expose without prompts.
+ *   - `autoMemoryEnabled: false` — SDK opt-out for auto-memory (defense in
+ *     depth; the tiny non-empty engraving/preset replacement is the primary
+ *     write-containment lever for Claude ACP).
+ *   - `hooks: {}` — configured-but-empty (NOT absent): inherits no operator
+ *     hook (mailbox absence by design) while keeping the compaction turn honest.
+ */
+export function overlaySettingsJson() {
+    return `${JSON.stringify({
+        permissions: { defaultMode: "default" },
+        autoMemoryEnabled: false,
+        hooks: {},
+    }, null, 2)}\n`;
+}
+/**
+ * The launch-env override an ACP child spawn must carry to redirect
+ * SettingsManager at the overlay. Pure — merge into the child's `env`.
+ */
+export function claudeLaunchEnvDefaults(overlayDir = CLAUDE_CONFIG_OVERLAY_DIR) {
+    return { CLAUDE_CONFIG_DIR: overlayDir };
+}
+/**
+ * Materialize / refresh the Claude config overlay. Idempotent: keeps correct
+ * symlinks, replaces wrong ones, removes stale entries cleanly. Safe to call on
+ * every ACP session bootstrap.
+ */
+export function ensureClaudeConfigOverlay(realDir = CLAUDE_REAL_CONFIG_DIR, overlayDir = CLAUDE_CONFIG_OVERLAY_DIR) {
+    mkdirSync(overlayDir, { recursive: true });
+    // settings.json — always (cheap unconditional rewrite keeps the override in
+    // place even if a prior process or operator edited it).
+    writeFileSync(join(overlayDir, "settings.json"), overlaySettingsJson(), "utf8");
+    // Empty dirs — overlay-owned; replace any prior symlink with a real dir.
+    for (const entry of OVERLAY_EMPTY_DIRS) {
+        const overlayPath = join(overlayDir, entry);
+        try {
+            const existing = lstatSync(overlayPath);
+            if (existing.isSymbolicLink() || !existing.isDirectory()) {
+                rmSync(overlayPath, { recursive: true, force: true });
+                mkdirSync(overlayPath, { recursive: true });
+            }
+        }
+        catch {
+            mkdirSync(overlayPath, { recursive: true });
+        }
+    }
+    // Symlink passthrough — only whitelisted entries that exist in realDir.
+    if (existsSync(realDir)) {
+        for (const entry of OVERLAY_PASSTHROUGH) {
+            const realPath = join(realDir, entry);
+            const overlayPath = join(overlayDir, entry);
+            if (!existsSync(realPath)) {
+                // Not present operator-side — remove any stale overlay copy.
+                try {
+                    lstatSync(overlayPath);
+                    rmSync(overlayPath, { recursive: true, force: true });
+                }
+                catch {
+                    // Doesn't exist — fine.
+                }
+                continue;
+            }
+            try {
+                const existing = lstatSync(overlayPath);
+                if (existing.isSymbolicLink()) {
+                    if (readlinkSync(overlayPath) === realPath)
+                        continue;
+                    unlinkSync(overlayPath);
+                }
+                else {
+                    rmSync(overlayPath, { recursive: true, force: true });
+                }
+            }
+            catch {
+                // Doesn't exist — fall through to symlink.
+            }
+            try {
+                symlinkSync(realPath, overlayPath);
+            }
+            catch (error) {
+                console.error(`[entwurf:claude-overlay] symlink failed for ${entry}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    // Stale cleanup — remove anything off the current allowlist. Binary-owned
+    // entries are preserved when real (binary authored them inside the overlay)
+    // but torn down when a stale symlink points at operator data.
+    for (const entry of readdirSync(overlayDir)) {
+        if (OVERLAY_PASSTHROUGH.has(entry))
+            continue;
+        if (OVERLAY_EMPTY_DIRS.has(entry))
+            continue;
+        const overlayPath = join(overlayDir, entry);
+        if (OVERLAY_BINARY_OWNED.has(entry)) {
+            try {
+                const stat = lstatSync(overlayPath);
+                if (stat.isSymbolicLink())
+                    rmSync(overlayPath, { force: true });
+            }
+            catch {
+                // Doesn't exist — fine; binary creates it on first launch.
+            }
+            continue;
+        }
+        try {
+            rmSync(overlayPath, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort; a stuck stale entry is annoying but not fatal.
+        }
+    }
+}

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

@@ -0,0 +1,153 @@
+// ACP plugin — Claude tool surface + exclude-tools truthfulness preflight (S2b).
+//
+// Two jobs:
+//   1. The curated Claude tool surface the bridge declares to claude-agent-acp
+//      via `_meta.claudeCode.options` (tools / permission allow / disallowed),
+//      built by `buildClaudeSessionMeta`.
+//   2. `assertExcludeToolsHonored` — a PREFLIGHT truthfulness check, NOT a wire
+//      read. There is no stable ACP surface that reports the backend's ACTUAL
+//      tool list (GPT S2b Q2), so the effective config WE supply is the SSOT:
+//      if pi has excluded a built-in the backend will still expose, the declared
+//      surface diverges from the actual one — we fail fast rather than lie.
+//
+// Claude-only scope (NEXT §스코프). The function keeps a `backend` field so the
+// honest-divergence logic stays explicit and the matrix gate can exercise both
+// the "claude narrows via tools" and "native always exposes" branches, but the
+// only backend this lane supplies is claude.
+//
+// Carrier guard (NEXT §S2-scout 핀1): `buildClaudeSessionMeta` only attaches
+// `_meta.systemPrompt` when a caller passes one. The shipped S2d path passes the
+// tiny non-empty engraving carrier (v1 preset replacement / memory containment);
+// an absent argument remains a true opt-out branch. Rich context is never carried
+// here — it rides the S2d first-user-message augment.
+/**
+ * pi baseline tools (Claude-capitalized) — mirrors what pi advertises as
+ * "Available tools:". Lowercase pi names map 1:1; keeping them aligned is the
+ * whole point of the truthfulness constraint.
+ */
+export const DEFAULT_CLAUDE_TOOLS = ["Read", "Bash", "Edit", "Write"];
+/** Permission allow list = the baseline surface + `mcp__*` (bridge MCP auto-allow). */
+export const DEFAULT_CLAUDE_PERMISSION_ALLOW = [
+    "Read(*)",
+    "Bash(*)",
+    "Edit(*)",
+    "Write(*)",
+    "mcp__*",
+];
+/**
+ * Deferred/extra tools the SDK advertises (via the ToolSearch system-reminder)
+ * that pi does NOT advertise in its fixed baseline — disallow them so the
+ * declared-vs-actual surfaces match. pi's own equivalents cover each
+ * (Cron→/schedule, Web→brave-search/summarize, Task+RemoteTrigger→entwurf, …).
+ * When the SDK adds a deferred tool, this list must follow.
+ */
+export const DEFAULT_CLAUDE_DISALLOWED_TOOLS = [
+    "AskUserQuestion",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "EnterPlanMode",
+    "EnterWorktree",
+    "ExitPlanMode",
+    "ExitWorktree",
+    "Monitor",
+    "NotebookEdit",
+    "PushNotification",
+    "RemoteTrigger",
+    "TaskCreate",
+    "TaskGet",
+    "TaskList",
+    "TaskOutput",
+    "TaskStop",
+    "TaskUpdate",
+    "WebFetch",
+    "WebSearch",
+];
+/**
+ * pi built-in tool names (lowercase) that map 1:1 onto a backend capability the
+ * ACP child ALWAYS provides. Extension tools (entwurf_v2, entwurf_peers, …) are
+ * pi-side and never reach the backend — excluding THEM is honest, so they are
+ * deliberately not listed here.
+ */
+export const PI_BUILTIN_BACKED_TOOLS = ["read", "bash", "edit", "write"];
+/**
+ * Fail-fast on a tool-surface lie. If pi has excluded a built-in the backend
+ * will still expose, the declared surface diverges from the actual one — reject
+ * up front instead of telling the model a tool is gone while the backend can
+ * still run it. Pure function (no IO).
+ *
+ * - Claude: backend builtins = `resolved.tools` ∩ the pi-backed builtin set
+ *   (lowercased). Drop `Read` from `tools` and excluding `read` becomes honest.
+ * - Other backends: assumed to always expose the full builtin set natively.
+ */
+export function assertExcludeToolsHonored(activeToolNames, resolved) {
+    const active = new Set(activeToolNames);
+    const backendBuiltins = resolved.backend === "claude"
+        ? resolved.tools.map((t) => t.toLowerCase()).filter((t) => PI_BUILTIN_BACKED_TOOLS.includes(t))
+        : [...PI_BUILTIN_BACKED_TOOLS];
+    const unhonored = backendBuiltins.filter((t) => !active.has(t));
+    if (unhonored.length > 0) {
+        const many = unhonored.length > 1;
+        throw new Error(`entwurf cannot honor --exclude-tools (${unhonored.join(", ")}) on the ${resolved.backend} backend: ` +
+            `the backend CLI still exposes ${many ? "these capabilities" : "this capability"} natively, so excluding ` +
+            `${many ? "them" : "it"} from pi's surface would make the declared tool set diverge from what the backend can ` +
+            `actually do. Restrict ${many ? "them" : "it"} via the backend's own tool config instead` +
+            (resolved.backend === "claude" ? " (provider settings 'tools' / 'disallowedTools')" : "") +
+            ". Extension tools (entwurf_v2, entwurf_peers) can be excluded freely — they are pi-side and never reach the backend.");
+    }
+}
+/**
+ * Build the `_meta` object handed to `newSession` for a Claude ACP session.
+ *
+ * `normalizedSystemPrompt` is OPTIONAL. The SHIPPED default supplies it (the
+ * non-empty v1 engraving): a string carrier makes claude-agent-acp REPLACE its
+ * `claude_code` preset, stripping auto-memory (see engraving.ts). When absent
+ * (operator opt-out — emptied engraving), the result carries NO `systemPrompt`
+ * key and claude-agent-acp keeps its default preset. Either way the carrier stays
+ * SHORT so it never grows past the SDK-default size (NEXT §S2-scout 핀1). Rich
+ * identity/context rides a first-user-message prepend, never this carrier.
+ */
+export function buildClaudeSessionMeta(params, normalizedSystemPrompt) {
+    const claudeCodeOptions = {
+        ...(params.modelId ? { model: params.modelId } : {}),
+        tools: [...params.tools],
+        settingSources: [...params.settingSources],
+        settings: {
+            permissions: {
+                allow: [...params.permissionAllow],
+            },
+            // Auto-memory containment, defense-in-depth (Detour C). The overlay's
+            // settings.json also pins `autoMemoryEnabled:false`, but production runs the
+            // query in SDK filesystem-isolation mode (`settingSources: []`), so that
+            // on-disk copy is never loaded — claude-agent-acp forwards our options
+            // verbatim (acp-agent.js: `...userProvidedOptions`) and the SDK skips
+            // ~/.claude/settings.json. This INLINE settings layer is independent of
+            // `settingSources`, so it IS honored — the live seal. Backstop only: the
+            // primary write-containment lever is the non-empty engraving carrier
+            // replacing the claude_code preset (which strips the auto-memory
+            // advertisement the model would otherwise act on). "knows-but-can't" here vs
+            // 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,
+        },
+    };
+    if (params.skillPlugins.length > 0) {
+        claudeCodeOptions.plugins = params.skillPlugins.map((path) => ({ type: "local", path }));
+    }
+    // Only emit when non-empty so `disallowedTools: []` opts fully out of the
+    // bridge's deferred-tool muting (the agent's own AskUserQuestion mute still
+    // applies — that is claude-agent-acp's call, not ours).
+    if (params.disallowedTools.length > 0) {
+        claudeCodeOptions.disallowedTools = [...params.disallowedTools];
+    }
+    if (params.strictMcpConfig) {
+        claudeCodeOptions.extraArgs = { "strict-mcp-config": null };
+    }
+    const meta = {
+        claudeCode: { options: claudeCodeOptions },
+    };
+    if (normalizedSystemPrompt) {
+        meta.systemPrompt = normalizedSystemPrompt;
+    }
+    return meta;
+}

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

@@ -3,20 +3,34 @@
  * (SE-1/SE-2 slice 2c). "If I enqueue a conversational reply to this target's mailbox
  * right now, will a model actually see it — or will it rot as garbage?"
  *
- * Two layers, both pure (facts injected, no IO):
+ * Three predicates, all pure (facts injected, no IO) — but on TWO different delivery
+ * axes that must never be collapsed into one (보정①):
  *
  *  - computeMetaReceiverActive(facts): the shared "is this receiver active?" atom —
  *    recordBacked AND ownerAlive AND watchArmed. This is the SAME conjunction the
  *    self-addressability predicate uses for its meta branch; both import it so the
  *    "active receiver" definition has ONE source of truth (concept shared, API split).
+ *    `watchArmed` is the MAILBOX-ONLY "idle-wake watch armed" signal (meta-session
+ *    receiver marker) — it belongs to the mailbox axis and nothing else.
  *
  *  - mailboxConversationalDeliverable(facts): the enqueue gate. A mailbox enqueue +
- *    doorbell only delivers for a SELF-FETCH backend (Claude Code / Codex / agy): the
- *    receiver drains its own inbox on wake. A DIRECT-INJECT backend (pi) has no
- *    mailbox drain at all — enqueuing for it is the SE-1 false success ("✓ delivered"
- *    into a void). So deliverable = wakeMode === "self-fetch" AND the receiver is
- *    active. This is the guard that the v1 fallback, MCP v1, pi-native v1, and the v2
- *    decider/send-fallback enqueue sites must all pass before writing a .msg (slice 2d).
+ *    doorbell only delivers for a SELF-FETCH backend (Claude Code): the receiver
+ *    drains its own inbox on wake. A DIRECT-INJECT backend (pi / codex / antigravity)
+ *    has no mailbox drain at all — enqueuing for it is the SE-1 false success
+ *    ("✓ delivered" into a void). So deliverable = wakeMode === "self-fetch" AND the
+ *    receiver is active. This is the guard that the v1 fallback, MCP v1, pi-native v1,
+ *    and the v2 decider/send-fallback enqueue sites must all pass before writing a
+ *    .msg (slice 2d).
+ *
+ *  - nativePushDeliverable(facts): the SEPARATE deliverability predicate for a
+ *    NATIVE-PUSH backend (antigravity). A native-push citizen has no mailbox and no
+ *    idle-wake watch — delivery is a direct injection into a LIVE app-server
+ *    conversation the adapter probe located. So deliverable = recordBacked AND
+ *    probeAlive. It MUST NOT reuse computeMetaReceiverActive: that atom folds in
+ *    `watchArmed`, so composing it here would smuggle a mailbox liveness fact into a
+ *    domain that has no mailbox (보정① — native-push replyable ≠ mailbox receiver).
+ *    The two axes are pinned apart in code so a future replyable-sender path cannot
+ *    quietly collapse them.
  *
  * The contract is "mailboxConversationalDeliverable", NOT a broad "deliverable": it is
  * specifically about a conversational reply that needs a live doorbell wake, NOT about
@@ -56,8 +70,10 @@ export function receiverMarkerMatchesIdentity(marker, identity) {
 }
 /**
  * The conversational-mailbox enqueue gate. False (no enqueue) unless the backend is
- * self-fetch AND the receiver is active. A direct-inject backend (pi) is refused
- * outright — it has no mailbox drain, so an enqueue would be a silent false success.
+ * self-fetch AND the receiver is active. A direct-inject backend (pi / codex /
+ * antigravity) is refused outright — it has no mailbox drain, so an enqueue would be a
+ * silent false success. A native-push backend's live delivery goes through
+ * nativePushDeliverable, not this gate.
  */
 export function mailboxConversationalDeliverable(facts) {
     if (facts.wakeMode !== "self-fetch") {
@@ -74,3 +90,20 @@ export function mailboxConversationalDeliverable(facts) {
             : `self-fetch receiver inactive — ${recv.reason}`,
     };
 }
+/**
+ * The native-push deliverability predicate (봉인 6). deliverable ⟺ recordBacked ∧
+ * probeAlive. This DELIBERATELY does NOT reuse computeMetaReceiverActive — that atom
+ * requires `watchArmed`, the mailbox-only "idle-wake watch armed" signal, which is
+ * meaningless for a backend with no mailbox (보정①). Fail-closed: an undefined fact
+ * is treated as false, never optimistic; each failure names its own cause so a
+ * record-less target is never conflated with a probe that found no live conversation.
+ */
+export function nativePushDeliverable(facts) {
+    if (facts.recordBacked !== true) {
+        return { deliverable: false, reason: "no backing meta-record" };
+    }
+    if (facts.probeAlive !== true) {
+        return { deliverable: false, reason: "adapter probe found no live native conversation" };
+    }
+    return { deliverable: true, reason: "record backed, native conversation probed alive" };
+}