@1agh/maude 0.45.1 → 0.46.0

package/apps/studio/acp/bridge.ts

@@ -15,11 +15,15 @@ import {
   type AvailableCommand,
   type Client,
   ClientSideConnection,
+  type CreateElicitationRequest,
+  type CreateElicitationResponse,
   ndJsonStream,
   PROTOCOL_VERSION,
   type PromptResponse,
   type RequestPermissionRequest,
   type RequestPermissionResponse,
+  type SessionConfigOption,
+  type SessionModeState,
   type SessionNotification,
   type SessionUpdate,
 } from '@agentclientprotocol/sdk';
@@ -46,30 +50,99 @@ export interface AcpBridgeOptions {
   plugins?: SdkPluginConfig[];
   /** Streamed `session/update` notifications relayed to the browser. */
   onUpdate: (update: SessionUpdate) => void;
-  /** Informational: a tool permission was auto-approved (transparency for the UI). */
+  /**
+   * Informational transparency callback: fires whenever the agent asks for a
+   * tool permission, REGARDLESS of how it's ultimately resolved. Kept
+   * alongside `onPermissionRequest` below (Milestone B, DDR-125 F2 retirement)
+   * so any existing audit/logging consumer keeps seeing every request.
+   */
   onPermission?: (req: RequestPermissionRequest) => void;
+  /**
+   * The actual approve/deny UI hook (retires DDR-125 F2's blanket auto-
+   * approve) — fires once per request with a fresh nonce `id`; the caller
+   * (index.ts) forwards it to the browser as a `permission-request` frame.
+   * The bridge awaits `resolvePermission(id, …)` before returning to the
+   * adapter — nothing is pre-decided here.
+   */
+  onPermissionRequest?: (id: string, req: RequestPermissionRequest) => void;
+  /**
+   * The elicitation-form UI hook (feature-acp-ask-user-question) — fires once
+   * per `unstable_createElicitation` call with a fresh nonce `id`, mirroring
+   * `onPermissionRequest` exactly. Carries BOTH `AskUserQuestion`-sourced forms
+   * AND any MCP-server-originated elicitation (same wire mechanism — see the
+   * plan's Research section); the bridge does not and cannot distinguish them.
+   * The bridge awaits `resolveElicitation(id, …)` before returning to the
+   * adapter.
+   */
+  onElicitationRequest?: (id: string, req: CreateElicitationRequest) => void;
+  /**
+   * Fires whenever a pending elicitation is settled, REGARDLESS of which path
+   * settled it (a client `elicitation-response`, a bridge-side timeout,
+   * `cancel()`, or `stop()`). A client-driven response already removes its own
+   * pending entry optimistically (see `respondElicitation` in acp-runtime.js),
+   * so for that path this is a harmless no-op notification; it exists for the
+   * paths the client can't otherwise learn about — a server-side timeout in
+   * particular used to leave the card showing a Submit button that was already
+   * dead (the bridge had moved on), with no visible feedback and no way for a
+   * click to do anything (dogfooding finding — "submit does nothing" after the
+   * card sat open long enough to time out).
+   */
+  onElicitationSettled?: (id: string) => void;
   /**
    * The agent's slash-command catalogue (`available_commands_update`) — drives
    * the composer autocomplete + inline command pill. Fires whenever the agent
    * (re)publishes the list; the manager caches the latest and pushes it to the UI.
    */
   onCommands?: (commands: AvailableCommand[]) => void;
+  /**
+   * The session's permission-mode roster + generic config-option set (models,
+   * effort, fast-mode, agent persona, …) — sourced live from the ACP session,
+   * never hardcoded (feature-acp-panel-dynamic-claude-code-capabilities).
+   * Fires once right after a session is established (create OR resume, AFTER
+   * any resume-replay window closes) and again on every `current_mode_update`
+   * / `config_option_update` notification.
+   */
+  onCaps?: (modes: SessionModeState | null, configOptions: SessionConfigOption[]) => void;
+  /** The agent-generated chat title (`session_info_update`) — fires at turn-end. */
+  onSessionInfo?: (info: { title?: string | null; updatedAt?: string | null }) => void;
+  /**
+   * Context-window usage + cost (`usage_update`, Milestone D) — fires after
+   * each result and, less often, on a `rate_limit_event` (carried in `_meta`).
+   * Chrome, not turn content — the client renders it as an ambient meter, not
+   * a message part.
+   */
+  onUsage?: (usage: BridgeUsage) => void;
+  /** Override for `PERMISSION_TIMEOUT_MS` (tests only — production always gets the real default). */
+  permissionTimeoutMs?: number;
 }
 
-type Spawned = ReturnType<typeof Bun.spawn>;
+/** The bridge's normalized shape of a `usage_update` notification. `rateLimit`
+ *  is the RAW `_meta["_claude/rateLimit"]` payload (an `SDKRateLimitInfo`) —
+ *  passed through opaque; `client/panels/acp-usage.js`'s `parseUsage` is
+ *  where it gets mapped to a friendly label, not here. */
+export interface BridgeUsage {
+  used: number;
+  size: number;
+  cost?: { amount: number; currency: string } | null;
+  rateLimit?: unknown;
+}
 
-/**
- * Effort → extended-thinking budget, fed to the adapter as `MAX_THINKING_TOKENS`
- * (it maps 0 → thinking disabled, a positive int → an enabled budget). `balanced`
- * leaves it unset so the agent uses Claude Code's own default.
- */
-const EFFORT_THINKING_TOKENS: Record<string, number | null> = {
-  fast: 0,
-  balanced: null,
-  thorough: 31999,
-};
+/** Flatten a `SessionConfigSelect.options` — a flat option array OR grouped
+ *  (`SessionConfigSelectGroup[]`) — into one list of `{value,name}` leaves. */
+function flattenSelectOptions(options: unknown): Array<{ value: string; name?: string | null }> {
+  const list = Array.isArray(options) ? options : [];
+  const out: Array<{ value: string; name?: string | null }> = [];
+  for (const o of list) {
+    if (o && typeof o === 'object' && Array.isArray((o as { options?: unknown }).options)) {
+      out.push(...(o as { options: Array<{ value: string; name?: string | null }> }).options);
+    } else if (o && typeof o === 'object' && 'value' in o) {
+      out.push(o as { value: string; name?: string | null });
+    }
+  }
+  return out;
+}
 
-export type AcpEffort = keyof typeof EFFORT_THINKING_TOKENS;
+type Spawned = ReturnType<typeof Bun.spawn>;
 
 // Real sessionIds are adapter-generated `randomUUID()`s. A persisted value that
 // doesn't look like one (corrupt sidecar, or a tracked file a cloned repo
@@ -84,6 +157,10 @@ const VALID_SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
 // bridge silent forever. Mirrors the `withTimeout`/`TIMED_OUT` pattern already
 // used for network calls in `apps/studio/git/service.ts`.
 const LOAD_SESSION_TIMEOUT_MS = 15_000;
+// RCA-G1 — cap the ACP handshake so a mis-launched runtime that never speaks ACP
+// surfaces an error instead of an infinite "Working…". Generous: covers a cold
+// first-spawn of the compiled adapter runtime, but well short of "forever".
+const INITIALIZE_TIMEOUT_MS = 30_000;
 const TIMED_OUT = Symbol('maude-acp-load-session-timeout');
 function withTimeout<T>(p: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT> {
   p.catch(() => {});
@@ -125,6 +202,40 @@ function withTimeout<T>(p: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT
  * `LoadSessionRequest` (schema/types.gen.d.ts) — `sessionFor`'s resume path
  * spreads this same object and adds `sessionId` rather than duplicating it.
  */
+// The curated tool allow-list every Maude bridge session auto-approves, so the
+// design workflow (edit a canvas, then shell out to the `maude` CLI + its design
+// helpers) runs without a permission prompt on EVERY step — the out-of-box
+// "Manual mode blocks every edit" complaint this closes (DDR-184). Deliberately
+// NARROW, and a complement to (not a reversal of) DDR-179's "mode picker stays
+// honest": the session mode is left untouched at its default, so anything NOT on
+// this list still routes through the real approve/deny gate (requestPermission →
+// PermissionPrompt) — arbitrary `Bash(curl …)`/`rm`, WebFetch, unknown MCP tools.
+//
+//  • File tools (Read/Edit/Write/Glob/Grep/NotebookEdit) — the canvas-editing
+//    surface. Auto-approving Edit/Write is the accepted residual: edits land in
+//    the served project (already the edit target) and are reversible via the
+//    `_history/` snapshot stack.
+//  • `Bash(maude:*)` — the SINGLE rule that covers the entire design-helper
+//    surface, because DDR-062 routes every helper through `maude design <verb>`
+//    (screenshot / draw-* / canvas-rects / probe-footage / …) and their own deps
+//    (agent-browser, playwright, svgo) run as CHILDREN of that one bash call, so
+//    they need no separate entry. Bash NOT starting with `maude` still prompts.
+//
+// SOURCE-OF-TRUTH GUARD: this list is asserted against the `maude design` verb
+// dispatch (`cli/commands/design.mjs`) + `plugins/design/dependencies.json` by
+// acp-session-allowed-tools.test.ts — a future helper that is NOT reached via
+// `maude design` (a brand-new top-level tool, not a new verb) fails that test
+// loudly instead of silently prompting the user mid-workflow.
+export const MAUDE_DEFAULT_ALLOWED_TOOLS: readonly string[] = [
+  'Read',
+  'Edit',
+  'Write',
+  'Glob',
+  'Grep',
+  'NotebookEdit',
+  'Bash(maude:*)',
+];
+
 export function newSessionParams(
   repoRoot: string,
   studioBrief?: string,
@@ -142,7 +253,15 @@ export function newSessionParams(
   // deputy chain (the DDR-143 guard #6 follow-up). The project's CLAUDE.md is read
   // via a separate path and is unaffected. Always injected — every Maude bridge
   // session is auto-approving. `...plugins` (DDR-143) rides the same options object.
-  const options: Record<string, unknown> = { settingSources: ['user'] };
+  const options: Record<string, unknown> = {
+    settingSources: ['user'],
+    // DDR-184 — auto-approve Maude's own first-party tool surface so the design
+    // workflow never stalls on a per-edit / per-`maude` permission prompt. Rides
+    // the same `_meta.claudeCode.options` spread as `plugins`/`settings` below
+    // (`...userProvidedOptions`, acp-agent.js:2333→2455) into the SDK's
+    // `allowedTools` (sdk.d.ts:1331). Everything off this list still prompts.
+    allowedTools: [...MAUDE_DEFAULT_ALLOWED_TOOLS],
+  };
   if (plugins && plugins.length > 0) {
     options.plugins = plugins;
     // DDR-168 — the bundled `design` plugin is now injected UNCONDITIONALLY
@@ -179,15 +298,58 @@ export function newSessionParams(
   };
 }
 
-/** Pick the most-permissive allow option, or null if the agent offered none. */
-function pickAllowOption(params: RequestPermissionRequest) {
-  const options = params.options ?? [];
-  return (
-    options.find((o) => o.kind === 'allow_always') ??
-    options.find((o) => o.kind === 'allow_once') ??
-    options.find((o) => typeof o.kind === 'string' && o.kind.startsWith('allow')) ??
-    null
-  );
+// Milestone B (DDR-125 F2 retirement) — how long a permission request waits
+// for a human decision before the bridge settles it itself. Generous (a
+// person reading a tool-call card and clicking a button, not a network hop)
+// but bounded so a request can never hang the turn forever. The default on
+// timeout — like on turn-cancel — is DENY (`cancelled`), never allow: this is
+// the security control, so failing open would defeat the point.
+const PERMISSION_TIMEOUT_MS = 120_000;
+
+// SECURITY (ethical-hacker finding, retroactive review) — a single agent turn
+// can legitimately issue several tool calls back to back (a burst is normal
+// agent behavior, not a bug — e.g. prompt-injected content directing several
+// actions in one turn), so "one per tool call" is NOT the natural ceiling the
+// original comment above assumed. Mirrors the elicitation channel's
+// MAX_PENDING_ELICITATIONS cap for the same reason: an unbounded queue lets a
+// backlog build silently (no depth indicator existed either — see
+// ChatPanel.jsx's queue-count render) and manufactures the exact "reflexive
+// Enter-mashing" precondition that made the wrong-default bug below
+// exploitable in practice. Denying beyond the cap is always the safe
+// direction — it degrades to "the user will have to re-trigger that action,"
+// never to a silent allow.
+export const MAX_PENDING_PERMISSIONS = 10;
+
+// feature-acp-ask-user-question, SECURITY (ethical-hacker finding) — unlike a
+// permission request (one per tool call, rate-limited by how fast a model can
+// call tools), an elicitation can be issued directly by any connected MCP
+// server with no such natural ceiling. Without a cap, a compromised/hostile
+// MCP server can flood `pendingElicitations` (unbounded memory growth) or
+// send an oversized `requestedSchema` (e.g. thousands of `oneOf` options) that
+// the client renders with no clamp — either can freeze the panel or force the
+// user into an endless Submit/Skip/Cancel loop just to get their composer
+// back. Both are enforced BEFORE a request is ever registered or forwarded to
+// the client — a request that trips either cap is declined immediately, the
+// same fail-closed outcome as a timeout.
+export const MAX_PENDING_ELICITATIONS = 5;
+export const MAX_ELICITATION_SCHEMA_PROPERTIES = 20;
+export const MAX_ELICITATION_SCHEMA_BYTES = 16_384;
+
+/** Exported for direct unit-testing of the bound math without needing a live
+ *  bridge/subprocess — see `test/acp-elicitation-bridge.test.ts`. */
+export function elicitationSchemaWithinBounds(schema: unknown): boolean {
+  if (!schema || typeof schema !== 'object') return true; // nothing to bound
+  const properties = (schema as { properties?: unknown }).properties;
+  if (properties && typeof properties === 'object') {
+    if (Object.keys(properties).length > MAX_ELICITATION_SCHEMA_PROPERTIES) return false;
+  }
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(schema);
+  } catch {
+    return false; // unserializable (e.g. a cycle) — never trust it
+  }
+  return serialized.length <= MAX_ELICITATION_SCHEMA_BYTES;
 }
 
 export class AcpBridge {
@@ -212,16 +374,69 @@ export class AcpBridge {
   /** True while `conn.loadSession()` is replaying a resumed session's history
    *  back through the `sessionUpdate` client callback — see the guard in `start()`. */
   private replaying = false;
-  // Model + effort are env-at-spawn (ANTHROPIC_MODEL / MAX_THINKING_TOKENS), so a
-  // change re-spawns the adapter. `desired*` is what the UI asked for; `active*`
-  // is what the running session was spawned with.
+  // The last-advertised capability set for the live session — the dynamic
+  // replacement for the old hardcoded MODELS/EFFORTS arrays (feature-acp-panel-
+  // dynamic-claude-code-capabilities). Also doubles as the server-side
+  // allowlist a `set-mode`/`set-config` WS frame is validated against
+  // (DDR-125 F1 — a loopback frame still can't pin an arbitrary value).
+  private lastModes: SessionModeState | null = null;
+  private lastConfigOptions: SessionConfigOption[] = [];
+  // The user's current model/effort/mode picks — no longer env-at-spawn
+  // (Task A3); applied ONCE, live, right after a session is established
+  // (create OR resume), never forcing a respawn. `null` = "leave the
+  // session's own default alone."
   private desiredModel: string | null = null;
-  private desiredEffort: AcpEffort = 'balanced';
-  private activeModel: string | null = null;
-  private activeEffort: AcpEffort = 'balanced';
+  private desiredEffort: string | null = null;
+  private desiredModeId: string | null = null;
+  // Milestone B — permission requests awaiting a human decision, keyed by the
+  // nonce handed to the client in the `permission-request` frame.
+  private pendingPermissions = new Map<
+    string,
+    {
+      resolve: (r: RequestPermissionResponse) => void;
+      timer: ReturnType<typeof setTimeout>;
+      /** The optionIds actually offered for THIS request — resolvePermission
+       *  fails closed (denies) on anything else, so a decision can't pin an
+       *  option that was never on the table (DDR-125 F1 posture). */
+      optionIds: Set<string>;
+    }
+  >();
+  // feature-acp-ask-user-question — elicitation-form requests awaiting a human
+  // decision, keyed by the nonce handed to the client in the
+  // `elicitation-request` frame. Parallel to `pendingPermissions` rather than
+  // sharing its Map: the two response shapes (`RequestPermissionResponse`'s
+  // `{outcome:{outcome,optionId?}}` vs `CreateElicitationResponse`'s
+  // `{action,content?}`) don't unify cleanly under one generic "pending
+  // client answer" type without a discriminated wrapper that would make BOTH
+  // call sites harder to read for no real gain (open decision #2 in the plan).
+  private pendingElicitations = new Map<
+    string,
+    {
+      resolve: (r: CreateElicitationResponse) => void;
+      timer: ReturnType<typeof setTimeout>;
+    }
+  >();
+  // Milestone D — the last-seen usage snapshot, cached the same way lastModes/
+  // lastConfigOptions are (mirrors the manager's latestCommands replay pattern).
+  private lastUsage: BridgeUsage | null = null;
 
   constructor(private readonly opts: AcpBridgeOptions) {}
 
+  /** The last-advertised mode roster + current mode (read-only snapshot). */
+  get modes(): SessionModeState | null {
+    return this.lastModes;
+  }
+
+  /** The last-advertised generic config-option set (read-only snapshot). */
+  get configOptions(): SessionConfigOption[] {
+    return this.lastConfigOptions;
+  }
+
+  /** The last-seen usage snapshot (read-only), or null before the first `usage_update`. */
+  get usage(): BridgeUsage | null {
+    return this.lastUsage;
+  }
+
   /** The session id of the most recent prompt (for the `connected` frame). */
   get sessionId(): string | null {
     return this.currentSession;
@@ -239,15 +454,94 @@ export class AcpBridge {
     this.sessionStorePath = path;
   }
 
-  /** Desired model (alias/id, or null for the user's default) + effort. Applied
-   *  on the next prompt — re-spawning the adapter only if it actually changed. */
-  setConfig(model: string | null, effort: AcpEffort): void {
-    this.desiredModel = model;
-    this.desiredEffort = effort in EFFORT_THINKING_TOKENS ? effort : 'balanced';
+  /**
+   * The user's current model/effort/mode picks (dynamic option ids/values —
+   * sourced from a PRIOR session's advertised `configOptions`/`modes`, never
+   * a hardcoded list). Stored, not applied immediately: `establishSession`
+   * live-applies them once, best-effort, right after the next session comes
+   * up (create OR resume) — see `applyDesiredConfigOnce`. Does NOT touch a
+   * session that's already established; use `setMode`/`setConfigOption` for
+   * a live mid-chat change.
+   */
+  setConfig(model: string | null, effort: string | null, modeId: string | null = null): void {
+    this.desiredModel = model || null;
+    this.desiredEffort = effort || null;
+    this.desiredModeId = modeId || null;
+  }
+
+  /**
+   * Live-set the session mode for `chatId` (Task A2/A4 — driven by a
+   * `set-mode` WS frame). Establishes the session first if none exists yet,
+   * so the picker works before the first prompt. The caller (index.ts)
+   * validates `modeId` against `this.modes` before invoking this.
+   */
+  async setMode(chatId: string, modeId: string): Promise<void> {
+    await this.ensureStarted();
+    const sessionId = await this.sessionFor(chatId);
+    if (!this.conn) throw new Error('ACP adapter not ready');
+    await this.conn.setSessionMode({ sessionId, modeId });
   }
 
-  private configChanged(): boolean {
-    return this.desiredModel !== this.activeModel || this.desiredEffort !== this.activeEffort;
+  /**
+   * Live-set one config option (model/effort/fast/…) for `chatId`. The
+   * response echoes the FULL refreshed option set (a model switch can add/
+   * remove the effort option, for instance) — fed back through `onCaps` so
+   * every listener sees the side effects, not just the option that changed.
+   */
+  async setConfigOption(chatId: string, configId: string, value: string): Promise<void> {
+    await this.ensureStarted();
+    const sessionId = await this.sessionFor(chatId);
+    if (!this.conn) throw new Error('ACP adapter not ready');
+    const response = await this.conn.setSessionConfigOption({ sessionId, configId, value });
+    this.lastConfigOptions = response.configOptions;
+    this.opts.onCaps?.(this.lastModes, this.lastConfigOptions);
+  }
+
+  /** True when `value` is currently offered for the select-type option `configId`. */
+  private optionOffers(configId: string, value: string): boolean {
+    const opt = this.lastConfigOptions.find((o) => o.id === configId);
+    if (opt?.type !== 'select') return false;
+    return flattenSelectOptions(opt.options).some((o) => o.value === value);
+  }
+
+  /**
+   * Reflect the user's persisted model/effort/mode picks onto a FRESHLY
+   * established session (Task A3) — replaces the old env-at-spawn + respawn
+   * dance with live `setSessionConfigOption`/`setSessionMode` calls, none of
+   * which tear down the running `claude` subprocess. Best-effort and ordered:
+   * model first (switching it can change which OTHER options — e.g. effort —
+   * are even offered), then effort, then mode. A pick that isn't advertised
+   * (e.g. an effort level unsupported by the model claude resolved to) is
+   * silently skipped, leaving the session's own default in place.
+   */
+  private async applyDesiredConfigOnce(sessionId: string): Promise<void> {
+    if (!this.conn) return;
+    try {
+      if (this.desiredModel && this.optionOffers('model', this.desiredModel)) {
+        const res = await this.conn.setSessionConfigOption({
+          sessionId,
+          configId: 'model',
+          value: this.desiredModel,
+        });
+        this.lastConfigOptions = res.configOptions;
+      }
+      if (this.desiredEffort && this.optionOffers('effort', this.desiredEffort)) {
+        const res = await this.conn.setSessionConfigOption({
+          sessionId,
+          configId: 'effort',
+          value: this.desiredEffort,
+        });
+        this.lastConfigOptions = res.configOptions;
+      }
+      if (
+        this.desiredModeId &&
+        this.lastModes?.availableModes.some((m) => m.id === this.desiredModeId)
+      ) {
+        await this.conn.setSessionMode({ sessionId, modeId: this.desiredModeId });
+      }
+    } catch {
+      /* best-effort — a stale/unsupported persisted pick just leaves the session default */
+    }
   }
 
   /** Spawn + handshake exactly once; concurrent callers share the same promise. */
@@ -297,6 +591,9 @@ export class AcpBridge {
 
     const params = newSessionParams(this.opts.repoRoot, this.opts.studioBrief, this.opts.plugins);
     const persistedId = await this.readPersistedSessionId();
+    let sessionId: string | undefined;
+    let modes: SessionModeState | null | undefined;
+    let configOptions: SessionConfigOption[] | null | undefined;
     if (persistedId) {
       try {
         this.replaying = true;
@@ -308,7 +605,9 @@ export class AcpBridge {
           throw new Error(`loadSession timed out after ${LOAD_SESSION_TIMEOUT_MS}ms`);
         }
         this.sessions.set(chatId, persistedId);
-        return persistedId;
+        sessionId = persistedId;
+        modes = result.modes;
+        configOptions = result.configOptions;
       } catch (err) {
         await this.appendTranscript({
           role: 'bootstrap',
@@ -320,10 +619,25 @@ export class AcpBridge {
       }
     }
 
-    const created = await this.conn.newSession(params);
-    this.sessions.set(chatId, created.sessionId);
-    await this.writePersistedSessionId(created.sessionId);
-    return created.sessionId;
+    if (sessionId === undefined) {
+      const created = await this.conn.newSession(params);
+      this.sessions.set(chatId, created.sessionId);
+      await this.writePersistedSessionId(created.sessionId);
+      sessionId = created.sessionId;
+      modes = created.modes;
+      configOptions = created.configOptions;
+    }
+
+    // Capture + apply + broadcast caps AFTER the resume-replay window closes
+    // (`this.replaying` back to false) — the initial state here is the real,
+    // current session state (the RPC response), never replayed history, but
+    // we still sequence it after the try/finally so nothing fires while a
+    // resume is nominally in flight.
+    this.lastModes = modes ?? null;
+    this.lastConfigOptions = configOptions ?? [];
+    await this.applyDesiredConfigOnce(sessionId);
+    this.opts.onCaps?.(this.lastModes, this.lastConfigOptions);
+    return sessionId;
   }
 
   /** Read the sessionId persisted for this chat by a prior bridge lifetime.
@@ -390,14 +704,19 @@ export class AcpBridge {
     delete env.MAUDE_TOKEN_ENDPOINT;
     // biome-ignore lint/performance/noDelete: security env-scrub — see above; `delete` is the intentional primitive here.
     delete env.MAUDE_TOKEN_KEY;
-    // Model + effort selection — config, NOT credentials, so they're added back.
-    this.activeModel = this.desiredModel;
-    this.activeEffort = this.desiredEffort;
-    if (this.activeModel) env.ANTHROPIC_MODEL = this.activeModel;
-    const thinking = EFFORT_THINKING_TOKENS[this.activeEffort];
-    if (thinking !== null && thinking !== undefined) env.MAX_THINKING_TOKENS = String(thinking);
-
-    const proc = Bun.spawn([resolveAgentRuntime(), adapterEntry], {
+    // Model + effort are no longer env-at-spawn (Task A3) — the adapter starts
+    // on its own default and `establishSession`/`applyDesiredConfigOnce` live-
+    // applies the user's persisted picks via `setSessionConfigOption` once the
+    // session (and its advertised options) exist. No respawn on a config change.
+
+    // RCA-G1 — resolve a runnable JS runtime. On a node/bun-less machine this
+    // falls back to our own compiled self, which must be spawned with
+    // BUN_BE_BUN=1 to behave as `bun` (else it re-runs the embedded server and
+    // the handshake below never completes → "Working…" forever). Set on `env`
+    // AFTER scrubAgentEnv (which doesn't touch BUN_BE_BUN).
+    const runtime = resolveAgentRuntime();
+    if (runtime.bunBeBun) env.BUN_BE_BUN = '1';
+    const proc = Bun.spawn([runtime.bin, adapterEntry], {
       cwd: this.opts.repoRoot,
       env,
       stdin: 'pipe',
@@ -433,10 +752,57 @@ export class AcpBridge {
 
     const client: Client = {
       sessionUpdate: (params: SessionNotification) => {
+        const u = params.update;
         // The command catalogue is chrome, not chat — surface it to the UI but
         // keep it out of the rendered turn + the persisted transcript.
-        if (params.update.sessionUpdate === 'available_commands_update') {
-          this.opts.onCommands?.(params.update.availableCommands ?? []);
+        if (u.sessionUpdate === 'available_commands_update') {
+          this.opts.onCommands?.(u.availableCommands ?? []);
+          return;
+        }
+        // Capability-channel notifications (feature-acp-panel-dynamic-claude-code-
+        // capabilities) are chrome too — same treatment as the command catalogue
+        // above, deliberately NOT gated by `this.replaying` (mirrors
+        // available_commands_update): a resumed session's `loadSession` replay
+        // walks prior MESSAGE content only (claude-agent-acp's
+        // replaySessionHistory), never re-emits these side-channel notifications,
+        // so there is nothing stale to guard against here.
+        if (u.sessionUpdate === 'current_mode_update') {
+          // Carries only the new currentModeId — merge into the cached roster,
+          // never replace it (availableModes doesn't change on a mode switch).
+          this.lastModes = this.lastModes
+            ? { ...this.lastModes, currentModeId: u.currentModeId }
+            : { currentModeId: u.currentModeId, availableModes: [] };
+          this.opts.onCaps?.(this.lastModes, this.lastConfigOptions);
+          return;
+        }
+        if (u.sessionUpdate === 'config_option_update') {
+          this.lastConfigOptions = u.configOptions ?? [];
+          // The adapter mirrors the current mode as a "mode"-id select option
+          // inside configOptions (claude-agent-acp's MODE_CONFIG_ID) but doesn't
+          // always pair that with a current_mode_update — e.g. `setSessionMode`
+          // itself only emits config_option_update. Cross-derive so the
+          // dedicated mode picker (driven off `lastModes`) stays correct either way.
+          const modeOpt = this.lastConfigOptions.find((o) => o.id === 'mode');
+          if (modeOpt && typeof modeOpt.currentValue === 'string') {
+            this.lastModes = this.lastModes
+              ? { ...this.lastModes, currentModeId: modeOpt.currentValue }
+              : { currentModeId: modeOpt.currentValue, availableModes: [] };
+          }
+          this.opts.onCaps?.(this.lastModes, this.lastConfigOptions);
+          return;
+        }
+        if (u.sessionUpdate === 'session_info_update') {
+          this.opts.onSessionInfo?.({ title: u.title, updatedAt: u.updatedAt });
+          return;
+        }
+        if (u.sessionUpdate === 'usage_update') {
+          this.lastUsage = {
+            used: u.used,
+            size: u.size,
+            cost: u.cost ?? null,
+            rateLimit: u._meta?.['_claude/rateLimit'],
+          };
+          this.opts.onUsage?.(this.lastUsage);
           return;
         }
         // `loadSession` replays the resumed session's entire prior history back
@@ -445,31 +811,125 @@ export class AcpBridge {
         // transcript and already rendered client-side, so forwarding/re-appending
         // it here would duplicate every message in the panel and the jsonl file.
         if (this.replaying) return;
-        this.opts.onUpdate(params.update);
-        void this.appendTranscript({ role: 'agent', update: params.update });
+        this.opts.onUpdate(u);
+        void this.appendTranscript({ role: 'agent', update: u });
       },
-      requestPermission: (params: RequestPermissionRequest): RequestPermissionResponse => {
-        // Auto-approve: the agent is the user's OWN local Claude editing their
-        // OWN project over loopback — granting it is the feature, mirroring
-        // Claude Code's trusted-session default. A manual approve/deny UI is a
-        // Task-3 follow-up; we surface the request so the panel can show it.
+      requestPermission: (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
+        // Milestone B (retires DDR-125 F2's blanket auto-approve) — the
+        // permission POLICY is now the selected session mode (sourced from
+        // Claude Code itself): `bypassPermissions`/`dontAsk` short-circuit
+        // adapter-side and never reach here at all; every OTHER mode routes
+        // through this real approve/deny gate. `onPermission` stays as a
+        // transparency callback (every request, however it resolves);
+        // `onPermissionRequest` is the actual UI hook the client answers.
         this.opts.onPermission?.(params);
-        const option = pickAllowOption(params);
-        if (!option) return { outcome: { outcome: 'cancelled' } };
-        return { outcome: { outcome: 'selected', optionId: option.optionId } };
+        // SECURITY (ethical-hacker finding) — bound queue depth before
+        // registering a pending entry, mirroring the elicitation channel's
+        // MAX_PENDING_ELICITATIONS cap. Deny immediately past the cap — safe
+        // by construction, since deny is this gate's own fail-closed default.
+        if (this.pendingPermissions.size >= MAX_PENDING_PERMISSIONS) {
+          return Promise.resolve({ outcome: { outcome: 'cancelled' } });
+        }
+        const id = crypto.randomUUID();
+        const optionIds = new Set((params.options ?? []).map((o) => o.optionId));
+        return new Promise<RequestPermissionResponse>((resolve) => {
+          const timer = setTimeout(
+            () => this.resolvePermission(id, 'cancelled'),
+            this.opts.permissionTimeoutMs ?? PERMISSION_TIMEOUT_MS
+          );
+          this.pendingPermissions.set(id, { resolve, timer, optionIds });
+          this.opts.onPermissionRequest?.(id, params);
+        });
+      },
+      unstable_createElicitation: (
+        params: CreateElicitationRequest
+      ): Promise<CreateElicitationResponse> => {
+        // feature-acp-ask-user-question — mirrors requestPermission's shape
+        // exactly. Fires for BOTH `AskUserQuestion` and any MCP-server
+        // elicitation (see the plan's Research section) — the toolCallId/
+        // session scope is not special-cased to assume it's always the
+        // built-in tool.
+        //
+        // SECURITY (ethical-hacker finding, post-implementation review) — only
+        // `form` mode was ever declared in `clientCapabilities` (never `url`),
+        // but capability negotiation is advisory, not enforced: a non-compliant
+        // adapter or a malicious/buggy MCP server could send `mode:'url'`
+        // anyway. Reject it HERE, structurally, rather than trusting the other
+        // side to honor what we advertised — `url`-mode has never had client
+        // rendering (no code anywhere reads/shows `params.url`), so forwarding
+        // it would have produced a bare "message + Submit" card the user could
+        // click through with no idea an out-of-band URL flow was actually being
+        // confirmed (a confused-consent primitive — see DDR-180).
+        if (params.mode !== 'form') {
+          return Promise.resolve({ action: 'decline' });
+        }
+        // SECURITY (ethical-hacker finding) — bound queue depth + schema size
+        // BEFORE registering a pending entry or forwarding anything to the
+        // client, so a flood or an oversized schema never reaches the
+        // renderer at all rather than being handled gracefully once there.
+        if (this.pendingElicitations.size >= MAX_PENDING_ELICITATIONS) {
+          return Promise.resolve({ action: 'decline' });
+        }
+        if (!elicitationSchemaWithinBounds(params.requestedSchema)) {
+          return Promise.resolve({ action: 'decline' });
+        }
+        const id = crypto.randomUUID();
+        return new Promise<CreateElicitationResponse>((resolve) => {
+          const timer = setTimeout(
+            () => this.resolveElicitation(id, { action: 'decline' }),
+            this.opts.permissionTimeoutMs ?? PERMISSION_TIMEOUT_MS
+          );
+          this.pendingElicitations.set(id, { resolve, timer });
+          this.opts.onElicitationRequest?.(id, params);
+        });
       },
     };
 
     const conn = new ClientSideConnection(() => client, stream);
     this.conn = conn;
 
-    await conn.initialize({
-      protocolVersion: PROTOCOL_VERSION,
-      // We don't expose the project filesystem to the agent over ACP — the
-      // spawned `claude` already has direct disk access to `cwd`, so advertising
-      // fs capabilities here would only duplicate (and widen) that surface.
-      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
-    });
+    // RCA-G1 — bound the handshake. If the spawned "adapter" is actually a
+    // mis-launched runtime that never speaks ACP (the exact node-less bug: a
+    // compiled sidecar re-run as a server instead of `bun`, before the
+    // BUN_BE_BUN fix, or any future runtime regression), `initialize()` never
+    // resolves and the panel hangs at "Working…" forever with no error. Time it
+    // out, tear down the dead child, and surface a real error the UI can show
+    // instead of an infinite spinner. Mirrors the `withTimeout` guard already
+    // used for `loadSession`.
+    const initResult = await withTimeout(
+      conn.initialize({
+        protocolVersion: PROTOCOL_VERSION,
+        // We don't expose the project filesystem to the agent over ACP — the
+        // spawned `claude` already has direct disk access to `cwd`, so advertising
+        // fs capabilities here would only duplicate (and widen) that surface.
+        // feature-acp-ask-user-question — declares `form` only, never `url`
+        // (an agent-chosen URL the user is directed to open is a materially
+        // bigger trust surface than a schema-driven form rendered entirely
+        // client-side — see the plan's Open decisions). This is also the
+        // single client-capability gate that unblocks the built-in
+        // `AskUserQuestion` tool AND any connected MCP server's elicitation
+        // requests (same wire mechanism, no sub-flag to separate them —
+        // acp-agent.js's `disallowedTools` check).
+        clientCapabilities: {
+          fs: { readTextFile: false, writeTextFile: false },
+          elicitation: { form: {} },
+        },
+      }),
+      INITIALIZE_TIMEOUT_MS
+    );
+    if (initResult === TIMED_OUT) {
+      this.conn = null;
+      try {
+        proc.kill();
+      } catch {
+        /* already gone */
+      }
+      this.proc = null;
+      throw new Error(
+        `AI editing couldn't start: the agent runtime didn't respond within ${INITIALIZE_TIMEOUT_MS / 1000}s. ` +
+          `Check that Claude Code is installed and signed in (Help ▸ Check AI editing readiness).`
+      );
+    }
     // Sessions are created lazily per chat (sessionFor) — not here.
   }
 
@@ -478,11 +938,6 @@ export class AcpBridge {
     text: string,
     chatId: string
   ): Promise<{ stopReason: PromptResponse['stopReason'] }> {
-    // Model/effort are env-at-spawn — if the user changed them, tear the adapter
-    // down so ensureStarted re-spawns with the new env (sessions re-create lazily).
-    if (this.conn && this.configChanged()) {
-      await this.stop();
-    }
     await this.ensureStarted();
     const conn = this.conn;
     if (!conn) throw new Error('ACP adapter not ready');
@@ -527,13 +982,110 @@ export class AcpBridge {
    * Best-effort: callers swallow errors (autocomplete degrades to the static list).
    */
   async warmUp(chatId: string): Promise<void> {
-    if (this.conn && this.configChanged()) await this.stop();
     await this.ensureStarted();
     await this.sessionFor(chatId);
   }
 
+  /**
+   * Settle a pending permission request (Milestone B). `decision` is either a
+   * `PermissionOption.optionId` the agent offered, or the literal `'cancelled'`
+   * (reject/deny — the timeout default and what a turn-cancel forces). A
+   * request that's already been settled or whose id is unknown (stale client,
+   * already timed out) is a silent no-op — never throws on a race. A
+   * `decision` that ISN'T `'cancelled'` and wasn't actually among the options
+   * offered for THIS request fails closed to `'cancelled'` too (DDR-125 F1 —
+   * a frame can't pin an option that was never on the table, e.g. a stale
+   * optionId replayed from a different, already-settled request).
+   */
+  resolvePermission(id: string, decision: string): void {
+    const pending = this.pendingPermissions.get(id);
+    if (!pending) return;
+    this.pendingPermissions.delete(id);
+    clearTimeout(pending.timer);
+    const optionId = decision !== 'cancelled' && pending.optionIds.has(decision) ? decision : null;
+    pending.resolve(
+      optionId
+        ? { outcome: { outcome: 'selected', optionId } }
+        : { outcome: { outcome: 'cancelled' } }
+    );
+  }
+
+  /** Deny every currently-pending permission request — turn-cancel and full
+   *  teardown must never leave one hanging on a decision that will now never
+   *  arrive (Milestone B: the default on ANY abandonment is deny, not allow). */
+  private denyAllPendingPermissions(): void {
+    for (const id of [...this.pendingPermissions.keys()]) this.resolvePermission(id, 'cancelled');
+  }
+
+  /**
+   * Settle a pending elicitation request (feature-acp-ask-user-question).
+   * `response` is the client's WS-frame payload — already validated shallowly
+   * by index.ts (a well-formed `{action, content?}`); this is still the last
+   * line of defense, so anything that isn't literally `accept` with a real
+   * `content` object, or literally `cancel`, collapses to `decline`. A
+   * request that's already settled or whose id is unknown (stale client,
+   * already timed out) is a silent no-op — never throws on a race. `decline`
+   * is deliberately NOT the same failure mode as a permission `cancelled`:
+   * per `applyAskElicitationResponse`'s documented contract, decline tells
+   * the model the user skipped (the turn continues), while `cancel` aborts
+   * the tool call — so a bridge-initiated fail-safe (timeout, turn-cancel,
+   * teardown) always declines, never cancels, unless the human explicitly
+   * clicked Cancel client-side.
+   */
+  resolveElicitation(id: string, response: { action?: unknown; content?: unknown }): void {
+    const pending = this.pendingElicitations.get(id);
+    if (!pending) return;
+    this.pendingElicitations.delete(id);
+    clearTimeout(pending.timer);
+    this.opts.onElicitationSettled?.(id);
+    if (
+      response.action === 'accept' &&
+      response.content &&
+      typeof response.content === 'object' &&
+      !Array.isArray(response.content)
+    ) {
+      // Validate each value against the wire-allowed ElicitationContentValue
+      // shape (string | number | boolean | string[]) — mirrors
+      // claude-agent-acp's own `acceptedElicitationContent` validation
+      // (confirmed on disk) exactly, so a value the adapter would itself
+      // reject never gets forwarded as though it were a real answer.
+      // `Object.create(null)` — not `{}` — for defense-in-depth parity with
+      // `acp-elicitation.js`'s `buildElicitationContent` (client-side sibling
+      // building the same shape): a hand-crafted `elicitation-response` frame
+      // reaches THIS function directly (index.ts only shallow-validates), so
+      // it's the actual last line of defense against a `__proto__`-keyed
+      // `content`, not the client-side builder the real UI happens to use.
+      const content: Record<string, string | number | boolean | string[]> = Object.create(null);
+      for (const [key, value] of Object.entries(response.content)) {
+        if (
+          typeof value === 'string' ||
+          typeof value === 'number' ||
+          typeof value === 'boolean' ||
+          (Array.isArray(value) && value.every((item) => typeof item === 'string'))
+        ) {
+          content[key] = value;
+        }
+      }
+      pending.resolve({ action: 'accept', content });
+    } else if (response.action === 'cancel') {
+      pending.resolve({ action: 'cancel' });
+    } else {
+      pending.resolve({ action: 'decline' });
+    }
+  }
+
+  /** Decline every currently-pending elicitation request — same fail-closed
+   *  discipline as `denyAllPendingPermissions`, called from the same places. */
+  private declineAllPendingElicitations(): void {
+    for (const id of [...this.pendingElicitations.keys()]) {
+      this.resolveElicitation(id, { action: 'decline' });
+    }
+  }
+
   /** Cancel the in-flight turn (no-op if nothing is running). */
   async cancel(): Promise<void> {
+    this.denyAllPendingPermissions();
+    this.declineAllPendingElicitations();
     if (this.conn && this.currentSession) {
       try {
         await this.conn.cancel({ sessionId: this.currentSession });
@@ -546,6 +1098,8 @@ export class AcpBridge {
   /** Tear down: cancel, kill the subprocess, drop all handles + sessions. */
   async stop(): Promise<void> {
     await this.cancel();
+    this.denyAllPendingPermissions(); // belt-and-suspenders — cancel() already does this
+    this.declineAllPendingElicitations(); // ditto
     try {
       this.proc?.kill();
     } catch {