@lucascouts/claude-agent-acp-plus 0.8.1 → 0.10.0

package/dist/acp-agent.js

@@ -1,8 +1,10 @@
 import { agent as acpAgent, methods, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk";
-import { deleteSession, getSessionInfo, getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
+import { deleteSession, getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
 import { GOAL_ACTIONS, GOAL_CONTROL_METHOD, GOAL_EXTENSION_VERSION, goalUpdateFromPrompt, parseGoalRequest, toGoalSnapshot, } from "./goal-extension.js";
+import { sanitizeTitle, SessionTitles } from "./session-titles.js";
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -14,22 +16,23 @@ import { filterDeprecatedModels } from "./model-deprecation.js";
 import { SettingsManager } from "./settings.js";
 import { createThinkingConfigOption, effectiveThinkingConfig, resolveThinkingSelection, THINKING_CONFIG_ID, } from "./thinking-option.js";
 import { handleRewindCommand, parseRewindInvocation } from "./rewind-command.js";
-import { applyTaskCreate, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
+import { ALLOW_BYPASS, resolvePermissionMode } from "./permissions/modes.js";
+import { normalizeDurablePermissionChangeSet } from "./permissions/normalization.js";
+import { buildClaudePermissionOptions } from "./permissions/options.js";
+import { buildClaudePermissionPresentation } from "./permissions/presentation.js";
+import { decodeClaudePermissionResponse } from "./permissions/response.js";
+import { activeUsageLimitMessage, airSessionFailureCapabilityMeta, assistantMessageText, createSessionFailureState, isSyntheticUsageLimitMessage, providerFailureCategory, SessionFailureController, sessionFailureMeta, supportsAirSessionFailures, } from "./session-failure-extension.js";
+import { AGENT_FILE_CHANGE_REPORT_CAPABILITY, agentFileChangeReportMeta, agentFileChangeReportRequestId, containsFileChangeAuditMarker, createFileChangeAuditSupport, createFileChangeAuditTurnState, FILE_CHANGE_AUDIT_SERVER_NAME, isFileChangeAuditReportPhase, isFileChangeAuditTool, supportsAgentFileChangeReport, } from "./file-change-audit.js";
+import { applyTaskCreate, applyTaskList, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, parseTaskListOutput, parseTaskUpdateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
+import { acceptedPlanToolResult, ExitPlanCoordinator, executionDiagnostic, exitPlanModeRawOutput, observeExitPlanToolResults, } from "./exit-plan.js";
+import { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
+import { parseToolResultMeta } from "./tool-result-meta.js";
+export { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
+import { MODE_CONFIG_ID, SessionModeManager } from "./session-mode.js";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
 const execFileAsync = promisify(execFile);
-const MAX_TITLE_LENGTH = 256;
-function sanitizeTitle(text) {
-    // Replace newlines and collapse whitespace
-    const sanitized = text
-        .replace(/[\r\n]+/g, " ")
-        .replace(/\s+/g, " ")
-        .trim();
-    if (sanitized.length <= MAX_TITLE_LENGTH) {
-        return sanitized;
-    }
-    return sanitized.slice(0, MAX_TITLE_LENGTH - 1) + "…";
-}
+const MAX_INLINE_FAILURE_TITLE_LENGTH = 256;
 const ZERO_USAGE = Object.freeze({
     input_tokens: 0,
     output_tokens: 0,
@@ -73,9 +76,13 @@ const STEER_METHOD = "_session/steering";
  *  turn — an internal Claude implementation detail, not part of the wire
  *  contract. `now` pre-empts the current generation and handles the message
  *  immediately (interrupting a single-shot response, or slotting in between a
- *  multi-step turn's tool calls). Maps to `SDKUserMessage.priority`; injected
- *  steering always uses `now` so the running turn adapts as soon as possible. */
-const STEER_PRIORITY = "now";
+ *  multi-step turn's tool calls), while `later` waits for a pending
+ *  permission/elicitation callback to settle instead of cancelling its ACP
+ *  request and hiding the client's user-input card (IJAI-1191). Maps to
+ *  `SDKUserMessage.priority`; injected steering uses `now` unless the session is
+ *  awaiting user input (see `Session.pendingUserInputCount`). */
+const STEER_PRIORITY_NOW = "now";
+const STEER_PRIORITY_LATER = "later";
 /** Validate raw JSON-RPC params into a {@link SteerRequest}. Kept minimal — the
  *  content blocks are handed to `promptToClaude`, which tolerates unknown block
  *  types — but `sessionId` and a non-empty `prompt` array are required. */
@@ -114,11 +121,13 @@ function parseSteerRequest(params) {
  *  result is the turn's real terminal.
  *
  *  Deliberately fail-OPEN: an unknown future kind defaults to the user
- *  lane. Misrouting a USER result into the autonomous lane hangs the
- *  prompt un-detectably (the result is skipped, its trailing idle absorbed
- *  as owed, so the #825 detector can't fire); misrouting an autonomous
- *  result into the user lane is the bounded misattribution class this set
- *  exists to reduce. */
+ *  lane — including `unclassified` (SDK 0.3.232+), the CLI's own "couldn't
+ *  attribute this" marker, which gets the same safe default. Misrouting a
+ *  USER result into the autonomous lane hangs the prompt un-detectably
+ *  (the result is skipped, its trailing idle absorbed as owed, so the
+ *  #825 detector can't fire); misrouting an autonomous result into the
+ *  user lane is the bounded misattribution class this set exists to
+ *  reduce. */
 const AUTONOMOUS_RESULT_ORIGINS = new Set([
     "task-notification",
     "peer",
@@ -157,17 +166,9 @@ function computeSessionFingerprint(params) {
     const servers = [...(params.mcpServers ?? [])].sort((a, b) => a.name.localeCompare(b.name));
     return JSON.stringify({ cwd: params.cwd, mcpServers: servers });
 }
-/**
- * The single provider ID this agent exposes via `providers/*`. Claude Code has
- * one LLM backend selected by protocol (anthropic / bedrock / vertex), so there
- * is exactly one configurable provider.
- */
-const PROVIDER_ID = "main";
-/**
- * Protocols the `main` provider can be configured with. These mirror the
- * env-var mappings understood by {@link createEnvForProvider}.
- */
 const SUPPORTED_PROTOCOLS = ["anthropic", "bedrock", "vertex"];
+const PROVIDER_ID = "main";
+const DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com";
 const SUBAGENT_TRANSCRIPT_CAPABILITY = "subagent-transcript";
 function supportsSubagentTranscript(capabilities) {
     return capabilities?._meta?.[SUBAGENT_TRANSCRIPT_CAPABILITY] === true;
@@ -296,9 +297,6 @@ function shouldHideClaudeAuth() {
  *  query stream has already ended (ran to `done` or died). The stream is not
  *  revivable, so the only recovery is a fresh session. */
 const SESSION_ENDED_MESSAGE = "The Claude Agent session has ended. Please start a new session.";
-// Bypass Permissions doesn't work if we are a root/sudo user
-const IS_ROOT = (process.geteuid?.() ?? process.getuid?.()) === 0;
-const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX;
 // Slash commands that the SDK handles locally without replaying the user
 // message and without invoking the model.
 const LOCAL_ONLY_COMMANDS = new Set(["/context", "/heapdump", "/extra-usage"]);
@@ -408,189 +406,6 @@ export function isSyntheticLoginMessage(apiMessage) {
         typeof block.text === "string" &&
         block.text.includes("Please run /login"));
 }
-const PERMISSION_MODE_ALIASES = {
-    auto: "auto",
-    default: "default",
-    // Claude Code 2.1.200 renamed the "default" mode to "Manual" and accepts
-    // `"defaultMode": "manual"` in settings.json; honor the same alias here.
-    manual: "default",
-    acceptedits: "acceptEdits",
-    dontask: "dontAsk",
-    plan: "plan",
-    bypasspermissions: "bypassPermissions",
-    bypass: "bypassPermissions",
-};
-export function resolvePermissionMode(defaultMode, logger = console) {
-    if (defaultMode === undefined) {
-        return "default";
-    }
-    if (typeof defaultMode !== "string") {
-        logger.error("Ignoring permissions.defaultMode from settings: expected a string.");
-        return "default";
-    }
-    const normalized = defaultMode.trim().toLowerCase();
-    if (normalized === "") {
-        logger.error("Ignoring permissions.defaultMode from settings: expected a non-empty string.");
-        return "default";
-    }
-    const mapped = PERMISSION_MODE_ALIASES[normalized];
-    if (!mapped) {
-        logger.error(`Ignoring permissions.defaultMode from settings: unknown value '${defaultMode}'.`);
-        return "default";
-    }
-    if (mapped === "bypassPermissions" && !ALLOW_BYPASS) {
-        logger.error("Ignoring permissions.defaultMode from settings: bypassPermissions is not available when running as root.");
-        return "default";
-    }
-    return mapped;
-}
-/**
- * Builds the label for the "Always Allow" permission option so the user can see
- * the exact scope they are committing to. Uses the SDK-provided suggestions
- * when available (e.g. `Bash(npm test:*)`) and falls back to naming the whole
- * tool so "Always Allow" is never a blank check without disclosure.
- *
- * Fork-only layer. Upstream #930 moved the scope disclosure out of the option
- * label and into `_meta.permission.changes`, leaving the label as a fixed
- * "Always Allow". No shipping client reads that metadata yet — Zed in
- * particular has no reference to it — so on the label alone the user would be
- * granting a rule they cannot see. This restores the disclosure in the label
- * WITHOUT dropping the upstream metadata: both travel on the same option, and
- * the label can be retired once a client renders the structured form.
- */
-export function describeAlwaysAllow(suggestions, toolName) {
-    if (!suggestions || suggestions.length === 0) {
-        return `Always Allow all ${toolName}`;
-    }
-    const ruleLabels = [];
-    const directories = [];
-    for (const update of suggestions) {
-        if (update.type === "addRules" && update.behavior === "allow") {
-            for (const rule of update.rules) {
-                ruleLabels.push(rule.ruleContent ? `${rule.toolName}(${rule.ruleContent})` : `all ${rule.toolName}`);
-            }
-        }
-        else if (update.type === "addDirectories") {
-            directories.push(...update.directories);
-        }
-    }
-    const parts = [];
-    if (ruleLabels.length > 0) {
-        parts.push(ruleLabels.join(", "));
-    }
-    if (directories.length > 0) {
-        parts.push(`access to ${directories.join(", ")}`);
-    }
-    if (parts.length === 0) {
-        return `Always Allow all ${toolName}`;
-    }
-    return `Always Allow ${parts.join(" and ")}`;
-}
-function permissionLifetime(destination) {
-    switch (destination) {
-        case "session":
-            return { scope: "session" };
-        case "cliArg":
-            return { scope: "process", storage: "cli_argument" };
-        case "userSettings":
-            return { scope: "persistent", storage: "user" };
-        case "projectSettings":
-            return { scope: "persistent", storage: "project" };
-        case "localSettings":
-            return { scope: "persistent", storage: "project_local" };
-        default:
-            return { scope: "unknown" };
-    }
-}
-function permissionMetadataForAlwaysAllow(suggestions, toolName) {
-    const effectiveSuggestions = suggestions && suggestions.length > 0
-        ? suggestions
-        : [
-            {
-                type: "addRules",
-                rules: [{ toolName }],
-                behavior: "allow",
-                destination: "session",
-            },
-        ];
-    const changes = [];
-    for (const update of effectiveSuggestions) {
-        switch (update.type) {
-            case "addRules":
-            case "removeRules":
-            case "replaceRules": {
-                const operation = update.type === "addRules" ? "add" : update.type === "removeRules" ? "remove" : "replace";
-                const targets = update.rules.map((rule) => ({
-                    type: "tool",
-                    toolName: rule.toolName,
-                    ...(rule.ruleContent
-                        ? {
-                            matcher: {
-                                type: "provider_rule",
-                                provider: "claudeCode",
-                                value: rule.ruleContent,
-                            },
-                        }
-                        : {}),
-                }));
-                const renderedRules = update.rules
-                    .map((rule) => rule.ruleContent
-                    ? `${rule.toolName} calls matching ${rule.ruleContent}`
-                    : `all ${rule.toolName} calls`)
-                    .join(", ");
-                const verb = operation === "add"
-                    ? update.behavior === "allow"
-                        ? "Allow"
-                        : update.behavior === "deny"
-                            ? "Deny"
-                            : "Ask before"
-                    : operation === "remove"
-                        ? `Remove ${update.behavior} rules for`
-                        : `Replace ${update.behavior} rules with`;
-                changes.push({
-                    type: "policy_rule",
-                    operation,
-                    ruleBehavior: update.behavior,
-                    description: `${verb} ${renderedRules}`,
-                    lifetime: permissionLifetime(update.destination),
-                    targets,
-                });
-                break;
-            }
-            case "addDirectories":
-            case "removeDirectories": {
-                const operation = update.type === "addDirectories" ? "add" : "remove";
-                changes.push({
-                    type: "policy_rule",
-                    operation,
-                    ruleBehavior: "allow",
-                    description: operation === "add"
-                        ? `Allow filesystem access under ${update.directories.join(", ")}`
-                        : `Remove additional filesystem access under ${update.directories.join(", ")}`,
-                    lifetime: permissionLifetime(update.destination),
-                    targets: update.directories.map((path) => ({
-                        type: "filesystem",
-                        matcher: { type: "directory", path },
-                    })),
-                });
-                break;
-            }
-            case "setMode":
-                changes.push({
-                    type: "permission_mode",
-                    operation: "set",
-                    provider: "claudeCode",
-                    mode: update.mode,
-                    description: `Set Claude Code permission mode to ${update.mode}`,
-                    lifetime: permissionLifetime(update.destination),
-                });
-                break;
-            default:
-                break;
-        }
-    }
-    return { version: 1, changes };
-}
 /**
  * Bridges {@link AcpClient} to the connection-scoped {@link AgentContext}
  * exposed by `AgentApp.connect(...)` as `connection.client`. The peer handle is
@@ -628,16 +443,38 @@ class ClientConnection {
         return this.ctx.notify(method, params);
     }
 }
+function raceWithAbort(operation, signal) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        const onAbort = () => {
+            cleanup();
+            reject(new Error("Tool use aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted) {
+            onAbort();
+        }
+        void operation.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
 export class ClaudeAcpAgent {
     sessions;
     client;
     clientCapabilities;
     logger;
+    sessionModes;
     gatewayAuthRequest;
-    /** Client-managed LLM routing set via `providers/set`. Process-scoped and
-     *  never persisted to disk (see the Configurable LLM Providers RFD). When
-     *  set, it takes precedence over {@link gatewayAuthRequest}. */
+    /** Set while ACP overrides the agent's native provider configuration. */
     providerConfig;
+    /** Serializes provider changes while every open query is recreated between turns. */
+    providerUpdate = null;
+    exitPlan;
     /** Grace period before a `session/cancel` forces a wedged prompt loop to
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
      *  tests can shrink it. */
@@ -646,6 +483,48 @@ export class ClaudeAcpAgent {
         this.sessions = {};
         this.client = client;
         this.logger = logger ?? console;
+        this.exitPlan = new ExitPlanCoordinator({
+            currentSession: (id) => this.sessions[id],
+            closeQueryStream: (session) => this.closeQueryStream(session),
+            restartSession: async (params, options) => {
+                await this.createSession(params, options);
+                const session = this.sessions[options.publicSessionId];
+                if (!session)
+                    throw new Error("Fresh Claude context was not created");
+                return session;
+            },
+            applyFastMode: (session, enabled) => this.applyFastMode(session, enabled),
+            sessionUpdate: (notification) => this.client.sessionUpdate(notification),
+            ensureConsumer: (session, id) => this.ensureConsumer(session, id),
+            logError: (message, error) => this.logger.error(message, error),
+            destroyReplacement: (id, session) => {
+                disarmForceCancel(session);
+                session.cancelController?.abort();
+                this.closeQueryStream(session);
+                session.abortController.abort();
+                if (this.sessions[id] === session)
+                    delete this.sessions[id];
+            },
+            settleCancelledTurn: (original, session, turn) => {
+                disarmForceCancel(session);
+                this.finishFileChangeAudit(session, turn, "cancelled");
+                turn.settled = true;
+                turn.resolve({ stopReason: "cancelled", usage: sessionUsage(original) });
+            },
+            settleFailedTurn: (session, turn, error) => {
+                disarmForceCancel(session);
+                this.finishFileChangeAudit(session, turn, "providerError");
+                turn.settled = true;
+                turn.reject(error);
+            },
+        });
+        this.sessionModes = new SessionModeManager({
+            getSession: (sessionId) => this.sessions[sessionId],
+            sessionEndedMessage: SESSION_ENDED_MESSAGE,
+            updateConfigOption: (sessionId, configId, value) => this.updateConfigOption(sessionId, configId, value),
+            sessionUpdate: (params) => this.client.sessionUpdate(params),
+            logError: (...args) => this.logger.error(...args),
+        });
     }
     async initialize(request) {
         this.clientCapabilities = request.clientCapabilities;
@@ -790,6 +669,7 @@ export class ClaudeAcpAgent {
             // steering extension contract: advertises the `_session/steering` request
             // so clients know they may inject a follow-up into a running turn.
             _meta: {
+                ...airSessionFailureCapabilityMeta(AGENT_FILE_CHANGE_REPORT_CAPABILITY),
                 steering: {
                     supported: true,
                 },
@@ -802,6 +682,8 @@ export class ClaudeAcpAgent {
         };
     }
     async newSession(params) {
+        if (this.providerUpdate)
+            await this.providerUpdate;
         const response = await this.createSession(params, {
             // Revisit these meta values once we support resume
             resume: params._meta?.claudeCode?.options?.resume,
@@ -813,6 +695,8 @@ export class ClaudeAcpAgent {
         return response;
     }
     async unstable_forkSession(params) {
+        if (this.providerUpdate)
+            await this.providerUpdate;
         const response = await this.createSession({
             cwd: params.cwd,
             mcpServers: params.mcpServers ?? [],
@@ -829,6 +713,8 @@ export class ClaudeAcpAgent {
         return response;
     }
     async resumeSession(params) {
+        if (this.providerUpdate)
+            await this.providerUpdate;
         const result = await this.getOrCreateSession(params);
         // Needs to happen after we return the session
         setTimeout(() => {
@@ -837,6 +723,8 @@ export class ClaudeAcpAgent {
         return result;
     }
     async loadSession(params) {
+        if (this.providerUpdate)
+            await this.providerUpdate;
         const result = await this.getOrCreateSession(params);
         await this.replaySessionHistory(params.sessionId);
         // Send available commands after replay so it doesn't interleave with history
@@ -862,40 +750,6 @@ export class ClaudeAcpAgent {
             sessions,
         };
     }
-    /** Read the SDK-maintained title for a session and, if it changed since the
-     *  last time we looked, notify the client with a `session_info_update`. The
-     *  SDK has no push event for the title it auto-generates in the background, so
-     *  we pull it at turn-end. A missing session file or read error is non-fatal:
-     *  the title is best-effort and another turn will retry. */
-    async maybeUpdateSessionTitle(sessionId, session) {
-        let info;
-        try {
-            info = await getSessionInfo(sessionId, { dir: session.cwd });
-        }
-        catch (error) {
-            this.logger.error(`Session ${sessionId}: failed to read session info: ${error}`);
-            return;
-        }
-        // `customTitle` is a user-set `/rename`; `summary` is the auto-generated
-        // title (or first prompt). Prefer the explicit title when present.
-        const rawTitle = info?.customTitle ?? info?.summary;
-        if (!rawTitle) {
-            return;
-        }
-        const title = sanitizeTitle(rawTitle);
-        if (title === session.lastTitle) {
-            return;
-        }
-        session.lastTitle = title;
-        await this.client.sessionUpdate({
-            sessionId,
-            update: {
-                sessionUpdate: "session_info_update",
-                title,
-                updatedAt: new Date(info.lastModified).toISOString(),
-            },
-        });
-    }
     async authenticate(_params) {
         if (_params.methodId === "gateway" || _params.methodId === "gateway-bedrock") {
             this.gatewayAuthRequest = _params;
@@ -903,21 +757,14 @@ export class ClaudeAcpAgent {
         }
         throw new Error("Method not implemented.");
     }
-    /**
-     * `providers/list` — returns the single client-configurable custom gateway
-     * provider (`main`). `current` carries only non-secret routing (never headers,
-     * which may hold secrets); only `apiType`/`baseUrl` are surfaced for UI
-     * display, and is `null` when the provider is not configured/disabled. The
-     * provider is optional (`required: false`): while disabled/unconfigured the
-     * agent falls back to its own default routing (normal Claude login).
-     */
     async unstable_listProviders(_params) {
-        const config = this.resolveProviderConfig();
+        const config = this.providerConfig ?? this.defaultProviderConfig();
+        this.logger.log(`[providers/list] apiType=${config.apiType} baseUrl=${config.baseUrl} overridden=${this.providerConfig !== undefined}`);
         const provider = {
             providerId: PROVIDER_ID,
             supported: SUPPORTED_PROTOCOLS,
             required: false,
-            current: config ? { apiType: config.apiType, baseUrl: config.baseUrl } : null,
+            current: { apiType: config.apiType, baseUrl: config.baseUrl },
         };
         return { providers: [provider] };
     }
@@ -955,34 +802,49 @@ export class ClaudeAcpAgent {
             }
             config.vertex = { projectId: vertex.projectId, region: vertex.region };
         }
-        this.providerConfig = config;
+        this.logger.log(`[providers/set] apiType=${config.apiType} baseUrl=${config.baseUrl} sessions=${Object.keys(this.sessions).length}`);
+        await this.enqueueProviderUpdate(config);
         return {};
     }
     /**
-     * `providers/disable` — disabling the `main` provider clears any client-managed
-     * routing (both a `providers/set` config and the legacy gateway auth request),
-     * so the agent reverts to its own default routing and `providers/list` reports
-     * `current: null`. Disabling any other (unknown) ID is treated as a successful
-     * no-op per the RFD's idempotency rule.
+     * `providers/disable` ends ACP ownership of the single mutually exclusive
+     * backend slot and restores the agent's native routing state.
      */
     async unstable_disableProvider(params) {
         if (params.providerId === PROVIDER_ID) {
-            this.providerConfig = undefined;
-            this.gatewayAuthRequest = undefined;
+            this.logger.log(`[providers/disable] sessions=${Object.keys(this.sessions).length}`);
+            await this.enqueueProviderUpdate(undefined);
         }
         // Unknown provider: idempotent success.
         return {};
     }
-    /**
-     * Resolve the effective client-managed routing config. `providers/set` takes
-     * precedence; otherwise fall back to the legacy gateway auth request. Returns
-     * `null` when neither is configured.
-     */
     resolveProviderConfig() {
-        if (this.providerConfig) {
-            return this.providerConfig;
+        return this.providerConfig ?? gatewayRequestToProviderConfig(this.gatewayAuthRequest);
+    }
+    defaultProviderConfig() {
+        const gatewayConfig = gatewayRequestToProviderConfig(this.gatewayAuthRequest);
+        if (gatewayConfig) {
+            return gatewayConfig;
+        }
+        if (process.env.CLAUDE_CODE_USE_BEDROCK) {
+            return {
+                apiType: "bedrock",
+                baseUrl: process.env.ANTHROPIC_BEDROCK_BASE_URL ?? "https://bedrock-runtime.amazonaws.com",
+                headers: {},
+            };
         }
-        return gatewayRequestToProviderConfig(this.gatewayAuthRequest);
+        if (process.env.CLAUDE_CODE_USE_VERTEX) {
+            return {
+                apiType: "vertex",
+                baseUrl: process.env.ANTHROPIC_VERTEX_BASE_URL ?? "https://aiplatform.googleapis.com",
+                headers: {},
+            };
+        }
+        return {
+            apiType: "anthropic",
+            baseUrl: process.env.ANTHROPIC_BASE_URL ?? DEFAULT_ANTHROPIC_BASE_URL,
+            headers: {},
+        };
     }
     async logout(_params) {
         // Clear in-memory gateway credentials supplied via `authenticate` and any
@@ -1012,6 +874,8 @@ export class ClaudeAcpAgent {
         }
     }
     async prompt(params) {
+        if (this.providerUpdate)
+            await this.providerUpdate;
         const session = this.sessions[params.sessionId];
         if (!session) {
             throw new Error("Session not found");
@@ -1093,6 +957,12 @@ export class ClaudeAcpAgent {
             }
             return { stopReason: "end_turn" };
         }
+        if (session.autoModeFallbackWarningPending) {
+            await this.sessionModes.publishFallbackWarning(params.sessionId, session);
+        }
+        if (Array.from(session.taskState.values()).some((task) => task.status !== "completed")) {
+            await this.publishTaskPlan(params.sessionId, session.taskState);
+        }
         // Lazy Thinking application (R1.3): a pending config change is applied by
         // recreating the SDK query with session resume BEFORE this turn is
         // enqueued — never mid-turn, so only when no other prompt is in flight. A
@@ -1126,6 +996,16 @@ export class ClaudeAcpAgent {
         // user message, so the consumer can't promote the turn from the echo.
         const firstText = params.prompt[0]?.type === "text" ? params.prompt[0].text : "";
         const isLocalOnlyCommand = firstText.startsWith("/") && LOCAL_ONLY_COMMANDS.has(firstText.split(" ", 1)[0]);
+        const fileChangeReportRequestId = supportsAgentFileChangeReport(this.clientCapabilities)
+            ? agentFileChangeReportRequestId(params._meta)
+            : undefined;
+        let fileChangeAudit;
+        if (fileChangeReportRequestId &&
+            !session.fileChangeReportRequestIds.has(fileChangeReportRequestId)) {
+            session.fileChangeReportRequestIds.add(fileChangeReportRequestId);
+            fileChangeAudit = createFileChangeAuditTurnState(fileChangeReportRequestId);
+        }
+        session.titles.onPrompt(params.prompt);
         // Each prompt is a Turn whose deferred the persistent consumer settles once
         // the turn's outcome is known. `prompt()` owns no loop: it enqueues the
         // turn, pushes the user message onto the streaming input, makes sure the
@@ -1133,13 +1013,24 @@ export class ClaudeAcpAgent {
         const turn = {
             promptUuid,
             isLocalOnlyCommand,
+            ...(fileChangeAudit ? { fileChangeAudit } : {}),
             settled: false,
             resolve: () => { },
             reject: () => { },
         };
+        let completeTurn;
+        turn.completion = new Promise((resolve) => {
+            completeTurn = resolve;
+        });
         const response = new Promise((resolve, reject) => {
-            turn.resolve = resolve;
-            turn.reject = reject;
+            turn.resolve = (result) => {
+                resolve(result);
+                completeTurn();
+            };
+            turn.reject = (error) => {
+                reject(error);
+                completeTurn();
+            };
         });
         session.turnQueue ??= [];
         session.turnQueue.push(turn);
@@ -1174,6 +1065,15 @@ export class ClaudeAcpAgent {
             },
         });
     }
+    async publishTaskPlan(sessionId, taskState) {
+        await this.client.sessionUpdate({
+            sessionId,
+            update: {
+                sessionUpdate: "plan",
+                entries: taskStateToPlanEntries(taskState),
+            },
+        });
+    }
     async publishGoalFromPrompt(sessionId, prompt, commandUuid) {
         const goalUpdate = goalUpdateFromPrompt(prompt);
         if (goalUpdate !== undefined) {
@@ -1213,11 +1113,14 @@ export class ClaudeAcpAgent {
      *  an `SDKUserMessage` onto the same streaming input, which the SDK routes
      *  into the in-flight turn. The injected message's echo carries a uuid that
      *  matches no queued turn, so the consumer drops it as an unrelated replay
-     *  without promoting/settling anything. It is delivered at {@link
-     *  STEER_PRIORITY} (`now`) so it pre-empts the current generation (interrupting
-     *  a single-shot response, or slotting in between a multi-step turn's tool
-     *  calls). The steered message's own output streams via `session/update`, not
-     *  this response.
+     *  without promoting/settling anything. It is normally delivered at {@link
+     *  STEER_PRIORITY_NOW} so it pre-empts the current generation (interrupting a
+     *  single-shot response, or slotting in between a multi-step turn's tool
+     *  calls). While a permission or elicitation is awaiting user input it uses
+     *  {@link STEER_PRIORITY_LATER} instead, because interrupting that SDK
+     *  callback cancels the ACP request and can strand the prompt (IJAI-1191).
+     *  The steered message's own output streams via `session/update`, not this
+     *  response.
      *
      *  Pre-empting means ABORTING: the interrupted cycle emits a `result` of its
      *  own and the steered message runs as a second one, so the turn is marked
@@ -1268,8 +1171,11 @@ export class ClaudeAcpAgent {
         const steeredUuid = randomUUID();
         userMessage.uuid = steeredUuid;
         // Deliver into the running turn rather than queuing behind it as a fresh
-        // prompt would.
-        userMessage.priority = STEER_PRIORITY;
+        // prompt would. A steer landing while the client has a permission or
+        // elicitation card open must not pre-empt it — the interrupt cancels that
+        // ACP request — so it waits for the LAST such request to settle instead.
+        userMessage.priority =
+            (session.pendingUserInputCount ?? 0) > 0 ? STEER_PRIORITY_LATER : STEER_PRIORITY_NOW;
         // Mark before the push and in the same synchronous section as the in-flight
         // check: the interrupt can have the CLI finalizing the aborted cycle by the
         // time the consumer next runs, and an unmarked result would settle the turn
@@ -1287,6 +1193,15 @@ export class ClaudeAcpAgent {
         await this.publishGoalFromPrompt(sessionId, firstText, steeredUuid);
         return { outcome: "injected" };
     }
+    /** Publish the audit terminal for every turn path that did not reach the
+     *  report tool. The support flips the turn state synchronously before its
+     *  transport await, so callers can stay fail-open and settle the ACP prompt
+     *  immediately without allowing a racing lifecycle path to publish twice. */
+    finishFileChangeAudit(session, turn, reason) {
+        if (!turn.fileChangeAudit || !session.fileChangeAuditSupport)
+            return;
+        void session.fileChangeAuditSupport.finishUnavailable(turn.fileChangeAudit, reason);
+    }
     /** Lazily start the per-session consumer that drains the SDK query stream for
      *  the session's whole life. Idempotent: only the first `prompt()` starts it. */
     ensureConsumer(session, sessionId) {
@@ -1321,6 +1236,8 @@ export class ClaudeAcpAgent {
         // it here so the subsequent `RequestError.internalError` can forward it to
         // clients as structured `data`, sparing them from pattern-matching on text.
         let lastAssistantError;
+        let lastAssistantWasUsageLimit = false;
+        let lastAssistantFailureTitle;
         // When a streaming classifier refuses a turn, the assistant message carries
         // stop_reason "refusal" and structured stop_details. We capture the
         // human-readable explanation so the terminal `result` can surface it.
@@ -1366,19 +1283,67 @@ export class ClaudeAcpAgent {
          *  as the turn's answer. */
         const sendUpdate = async (notification) => {
             const { update } = notification;
+            if (isFileChangeAuditReportPhase(session.activeTurn?.fileChangeAudit) &&
+                (update.sessionUpdate === "agent_message_chunk" ||
+                    update.sessionUpdate === "agent_thought_chunk" ||
+                    update.sessionUpdate === "user_message_chunk" ||
+                    update.sessionUpdate === "tool_call" ||
+                    update.sessionUpdate === "tool_call_update")) {
+                return;
+            }
             if (update.sessionUpdate === "agent_message_chunk") {
                 const claudeMeta = update._meta?.claudeCode;
                 if (!claudeMeta?.parentToolUseId) {
                     session.emittedAssistantText = true;
+                    session.titles.onAssistantText(update.content);
                 }
             }
             await this.client.sessionUpdate(notification);
         };
+        let pendingWorkerShutdown = false;
+        const isCurrentConsumer = () => this.sessions[params.sessionId] === session;
+        const sessionFailures = new SessionFailureController({
+            sessionId: params.sessionId,
+            state: session.sessionFailureState,
+            capabilities: this.clientCapabilities,
+            isCurrent: isCurrentConsumer,
+            sendUpdate,
+            logger: this.logger,
+        });
+        const createSessionFailure = async (kind, options = {}) => {
+            const turnId = options.turnScoped === false ? undefined : session.activeTurn?.promptUuid;
+            return sessionFailures.prepare(kind, {
+                turnId,
+                sessionScoped: options.turnScoped === false,
+                title: options.title,
+                details: options.details,
+                severity: options.severity,
+            });
+        };
+        const publishSessionFailure = async (kind, options = {}) => {
+            const turnId = options.turnScoped === false ? undefined : session.activeTurn?.promptUuid;
+            await sessionFailures.publish(kind, {
+                turnId,
+                sessionScoped: options.turnScoped === false,
+                title: options.title,
+                details: options.details,
+                severity: options.severity,
+            });
+        };
+        const clearFailuresFromEarlierTurns = async () => {
+            const activeTurnId = session.activeTurn?.promptUuid;
+            // Advisories carry no turnId, so without the guard every turn boundary would sweep them away.
+            // They are session-scoped and stay until superseded or dismissed by the user.
+            await sessionFailures.clear((failure) => failure.recoveryPolicy === "next_attempt" && failure.turnId !== activeTurnId);
+        };
+        const internalErrorForClient = (data, rawDetail) => RequestError.internalError(data, supportsAirSessionFailures(this.clientCapabilities) ? undefined : rawDetail);
         const resetTurnScratch = () => {
             lastAssistantTotalUsage = null;
             lastAssistantUsage = null;
             lastAssistantModel = null;
             lastAssistantError = undefined;
+            lastAssistantWasUsageLimit = false;
+            lastAssistantFailureTitle = undefined;
             lastRefusalExplanation = null;
             compactionInProgress = false;
             // Do NOT reset currentStreamMessageId or streamedBlocks here. Turn
@@ -1390,12 +1355,14 @@ export class ClaudeAcpAgent {
             // cleared when each consolidated message consumes it. #785 stopped
             // resetting the streamed-content tracking here but left this line.
             stopReason = "end_turn";
-            session.accumulatedUsage = {
+            session.accumulatedUsage = session.activeTurn?.carriedUsage ?? {
                 inputTokens: 0,
                 outputTokens: 0,
                 cachedReadTokens: 0,
                 cachedWriteTokens: 0,
             };
+            if (session.activeTurn)
+                session.activeTurn.carriedUsage = undefined;
         };
         /** Promote a queued turn to active: it becomes the one output is attributed
          *  to, and its scratch starts fresh. Clears the cancelled flag so a turn
@@ -1622,11 +1589,14 @@ export class ClaudeAcpAgent {
         };
         /** Settle the active turn's deferred exactly once, disarm the force-cancel
          *  backstop (the turn is over), and drop it from the queue. */
-        const settleActive = (result) => {
+        const settleActive = (result, auditReason = result.stopReason === "cancelled"
+            ? "cancelled"
+            : "notReported") => {
             const turn = session.activeTurn;
             if (!turn || turn.settled) {
                 return;
             }
+            this.finishFileChangeAudit(session, turn, auditReason);
             // Captured before the settled flip below (isHeldOpen tests !settled).
             const wasHeld = isHeldOpen(turn);
             turn.settled = true;
@@ -1657,8 +1627,10 @@ export class ClaudeAcpAgent {
             disarmForceCancel(session);
             const turn = session.activeTurn;
             if (!turn || turn.settled) {
+                this.logger.error(`Session ${params.sessionId}: cannot fail active turn because no unsettled active turn exists: ${error}`);
                 return;
             }
+            this.finishFileChangeAudit(session, turn, "providerError");
             turn.settled = true;
             session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
             session.activeTurn = null;
@@ -1670,6 +1642,31 @@ export class ClaudeAcpAgent {
             session.emittedAssistantText = false;
             turn.reject(error);
         };
+        /** Complete a negotiated terminal failure on the prompt response itself,
+         *  which is the canonical AIR carrier. Legacy clients keep the historical
+         *  JSON-RPC rejection path. */
+        const failActiveWithSessionFailure = async (kind, error, title) => {
+            if (!supportsAirSessionFailures(this.clientCapabilities)) {
+                failActive(error);
+                return;
+            }
+            if (!session.activeTurn || session.activeTurn.settled) {
+                this.logger.error(`Session ${params.sessionId}: cannot attach ${kind} to a prompt response because no active turn exists; publishing a session-scoped failure`);
+                await publishSessionFailure(kind, { turnScoped: false, title });
+                return;
+            }
+            const failure = await createSessionFailure(kind, { title });
+            if (!failure) {
+                failActive(error);
+                return;
+            }
+            sessionFailures.recordActive(failure);
+            settleActive({
+                stopReason: "end_turn",
+                usage: sessionUsage(session),
+                _meta: sessionFailureMeta(failure),
+            }, "providerError");
+        };
         /** Reject every in-flight turn — used when the stream dies. */
         const failAllTurns = (error) => {
             disarmForceCancel(session);
@@ -1680,6 +1677,7 @@ export class ClaudeAcpAgent {
             session.turnQueue = [];
             for (const turn of turns) {
                 if (!turn.settled) {
+                    this.finishFileChangeAudit(session, turn, "providerError");
                     const wasHeld = isHeldOpen(turn);
                     turn.settled = true;
                     if (wasHeld) {
@@ -1752,7 +1750,9 @@ export class ClaudeAcpAgent {
                         // spent would never drain (it would swallow an unrelated later
                         // echo-less result instead).
                         const active = session.activeTurn;
-                        if (active.commandFinished === "completed" || active.commandFinished === "discarded") {
+                        if (active.commandFinished === "completed" ||
+                            active.commandFinished === "discarded" ||
+                            active.commandFinished === "refused") {
                             // Finished SDK-side; any result already passed. Nothing to
                             // track.
                         }
@@ -1812,6 +1812,24 @@ export class ClaudeAcpAgent {
                     if (session.query !== myQuery) {
                         return;
                     }
+                    if (pendingWorkerShutdown) {
+                        pendingWorkerShutdown = false;
+                        if (session.activeTurn) {
+                            if (!isHeldOpen(session.activeTurn)) {
+                                await failActiveWithSessionFailure("worker_shutdown", internalErrorForClient({ errorKind: "worker_shutdown" }));
+                            }
+                            else {
+                                // The held turn already has its authoritative terminal outcome,
+                                // but EOF permanently closes the non-revivable Query. Preserve
+                                // the turn result below and report the independent session-health
+                                // failure without a turnId so AIR can offer a new session.
+                                await publishSessionFailure("worker_shutdown", { turnScoped: false });
+                            }
+                        }
+                        else {
+                            await publishSessionFailure("worker_shutdown", { turnScoped: false });
+                        }
+                    }
                     // The stream ended. Settle the in-flight turns FIRST, then release the
                     // stream resources — same order as the error paths (failAllTurns before
                     // closeQueryStream). Settling is the user-facing contract; resource
@@ -1835,6 +1853,7 @@ export class ClaudeAcpAgent {
                     // still here was enqueued afterward and was not part of the cancel.)
                     for (const queued of [...(session.turnQueue ?? [])]) {
                         if (!queued.settled) {
+                            this.finishFileChangeAudit(session, queued, "providerError");
                             queued.settled = true;
                             queued.reject(RequestError.internalError(undefined, SESSION_ENDED_MESSAGE));
                         }
@@ -1856,7 +1875,7 @@ export class ClaudeAcpAgent {
                 }
                 // CLIs 2.1.206+ (capability msg_lifecycle_v1) report the fate of every
                 // uuid-stamped queued command (queued/started/completed/cancelled/
-                // discarded) as `command_lifecycle` frames — 2-3 per prompt, since
+                // discarded/refused) as `command_lifecycle` frames — 2-3 per prompt, since
                 // prompt() stamps a uuid on every message. The frame is @internal and
                 // absent from the SDKMessage union, so handle it BEFORE the exhaustive
                 // switch: it must not reach `unreachable`'s error log, and a `case`
@@ -1891,6 +1910,7 @@ export class ClaudeAcpAgent {
                         }
                         case "completed":
                         case "discarded":
+                        case "refused":
                         case "cancelled": {
                             // Terminal frames. Latch the fate on a still-queued turn so a
                             // later cancel() doesn't seed an orphan entry for a command
@@ -1924,6 +1944,9 @@ export class ClaudeAcpAgent {
                             // command folded into another turn whose result is attributed
                             // elsewhere — either way no echo-less result remains to skip.
                             // "discarded" = session ended with it still queued; no result.
+                            // "refused" (2.1.238+) = a cross-session peer message declined
+                            // by receive-side policy before dispatch; never a prompt-lane
+                            // command of ours, and no result will ever come.
                             session.orphanCommands?.delete(frame.command_uuid);
                             break;
                         }
@@ -1963,6 +1986,23 @@ export class ClaudeAcpAgent {
                                 // updated Fast mode state; reconcile it with what we seeded at
                                 // session creation.
                                 await this.syncFastModeState(message.session_id, session, message.fast_mode_state, message.fast_mode_disabled_reason);
+                                // Terminal-bound slash commands (absent when none, and on
+                                // older CLIs). The session/new advertisement runs before any
+                                // init frame can be observed, so the first latch (or a
+                                // genuine change) re-publishes the now-filtered list.
+                                if (message.terminal_slash_commands &&
+                                    JSON.stringify(message.terminal_slash_commands) !==
+                                        JSON.stringify(session.terminalSlashCommands)) {
+                                    session.terminalSlashCommands = message.terminal_slash_commands;
+                                    try {
+                                        await this.sendAvailableCommandsUpdate(message.session_id);
+                                    }
+                                    catch (error) {
+                                        // Advisory reconcile only — the client keeps its current
+                                        // (unfiltered) list; never fail the turn over it.
+                                        this.logger.error(`Failed to re-advertise slash commands: ${error}`);
+                                    }
+                                }
                                 break;
                             case "status": {
                                 // These banners count as delivered text (via sendUpdate), so
@@ -2030,6 +2070,7 @@ export class ClaudeAcpAgent {
                                 const usedTokens = await fetchContextUsedTokens(session.query, this.logger);
                                 lastAssistantUsage = null;
                                 lastAssistantTotalUsage = usedTokens ?? 0;
+                                session.contextUsedTokens = usedTokens ?? 0;
                                 await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
@@ -2155,13 +2196,11 @@ export class ClaudeAcpAgent {
                                         // the next prompt; only a timer could tell those apart.
                                         this.logger.error(`Session ${params.sessionId}: SDK went idle without emitting a result ` +
                                             `for the active turn; failing the in-flight prompt (issue #825)`);
-                                        failActive(RequestError.internalError(errorKindData("no_result"), TURN_NO_RESULT_MESSAGE));
+                                        await failActiveWithSessionFailure("internal_error", RequestError.internalError(errorKindData("no_result"), TURN_NO_RESULT_MESSAGE), TURN_NO_RESULT_MESSAGE);
                                     }
-                                    // The SDK generates the session title in a background task and
-                                    // persists it to the session file; `idle` is the turn-over
-                                    // signal, so it's the point at which a new title may have
-                                    // landed. Push it to the client if it changed.
-                                    await this.maybeUpdateSessionTitle(params.sessionId, session);
+                                    // Turn-over is when a title may have landed or become
+                                    // generatable; see SessionTitles.onTurnEnd.
+                                    await session.titles.onTurnEnd(session);
                                 }
                                 break;
                             }
@@ -2213,7 +2252,7 @@ export class ClaudeAcpAgent {
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "available_commands_update",
-                                        availableCommands: getAvailableSlashCommands(message.commands),
+                                        availableCommands: getAvailableSlashCommands(message.commands, session.terminalSlashCommands),
                                     },
                                 });
                                 break;
@@ -2355,9 +2394,14 @@ export class ClaudeAcpAgent {
                                 }
                                 break;
                             case "worker_shutting_down":
-                                // A Remote Control worker announced a graceful teardown. This is a
-                                // live-tail signal for remote clients to explain why a session went
-                                // away; it's not meaningful for a local stdio ACP session.
+                                // Defer until stream end. The announcement is durable and may be
+                                // replayed before later frames, but those frames do not prove that
+                                // a new worker epoch began: they can be buffered output from the
+                                // shutting-down worker. Keep the signal armed until the transport
+                                // actually ends. Deliberately do not add a quiet-period timer: the
+                                // iterator has no replay/live boundary, so a timeout could publish
+                                // while a slow replay is still in flight.
+                                pendingWorkerShutdown = true;
                                 break;
                             case "elicitation_complete": {
                                 // A url-mode MCP elicitation finished server-side. Let the client
@@ -2377,10 +2421,21 @@ export class ClaudeAcpAgent {
                             }
                             case "plugin_install":
                             case "notification":
-                            case "api_retry":
                             case "thinking_tokens":
                                 // Todo: process via status api: https://docs.claude.com/en/docs/claude-code/hooks#hook-output
                                 break;
+                            case "api_retry": {
+                                const title = message.error_status === null
+                                    ? `Reconnecting to Claude, attempt ${message.attempt} of ${message.max_retries}.`
+                                    : `Retrying Claude, attempt ${message.attempt} of ${message.max_retries}.`;
+                                await publishSessionFailure(message.error_status === null
+                                    ? "transport_lost"
+                                    : providerFailureCategory(message.error), {
+                                    title,
+                                    severity: "warning",
+                                });
+                                break;
+                            }
                             case "model_refusal_fallback": {
                                 // The SDK retried a refused turn on the fallback model and made
                                 // the swap persistent for the session. Without a notice the
@@ -2394,26 +2449,53 @@ export class ClaudeAcpAgent {
                                 // CLIs, where "revert" marked a turn-only fallback — for that
                                 // direction the session stays on the original model, so skip
                                 // the persistent-swap claim and the state sync.
-                                const persistent = message.direction !== "revert";
+                                //
+                                // `scope` (CLI 2.1.232+) marks WHERE the fallback happened:
+                                // "local" means a subagent / side-question / background fork
+                                // response fell back and the session model is unchanged, so
+                                // syncing the picker would advertise a model the session
+                                // isn't running. Absent scope means an older CLI, where every
+                                // retry was a session-level swap — treat as "session".
+                                const local = message.scope === "local";
+                                const persistent = message.direction !== "revert" && !local;
                                 const category = message.api_refusal_category
                                     ? ` (${message.api_refusal_category})`
                                     : "";
-                                const explanation = message.api_refusal_explanation
-                                    ? `\n\n${message.api_refusal_explanation}`
-                                    : "";
                                 const outcome = persistent
                                     ? `The session will continue on ${message.fallback_model}.`
-                                    : `The session stays on ${message.original_model}.`;
-                                await sendUpdate({
-                                    sessionId: message.session_id,
-                                    update: {
-                                        sessionUpdate: "agent_message_chunk",
-                                        content: {
-                                            type: "text",
-                                            text: `**Model fallback:** ${message.original_model} declined this request${category}; retried with ${message.fallback_model}. ${outcome}${explanation}`,
+                                    : local
+                                        ? `Only that response came from ${message.fallback_model}; the session stays on ${message.original_model}.`
+                                        : `The session stays on ${message.original_model}.`;
+                                const fallbackSummary = `${message.original_model} declined this request${category}; ` +
+                                    `retried with ${message.fallback_model}. ${outcome}`;
+                                const explanation = message.api_refusal_explanation || undefined;
+                                const fallbackNotice = explanation
+                                    ? `${fallbackSummary}\n\n${explanation}`
+                                    : fallbackSummary;
+                                // A silent model swap is a session-level advisory, not something the model said.
+                                // Clients that negotiated typed records get it as one; the rest keep the bold-label
+                                // transcript line, which was the only way to flag it before.
+                                if (supportsAirSessionFailures(this.clientCapabilities)) {
+                                    const useDetails = explanation !== undefined &&
+                                        fallbackSummary.length + 2 + explanation.length >
+                                            MAX_INLINE_FAILURE_TITLE_LENGTH;
+                                    await publishSessionFailure("advisory", {
+                                        title: useDetails ? fallbackSummary : fallbackNotice,
+                                        ...(useDetails ? { details: explanation } : {}),
+                                    });
+                                }
+                                else {
+                                    await sendUpdate({
+                                        sessionId: message.session_id,
+                                        update: {
+                                            sessionUpdate: "agent_message_chunk",
+                                            content: {
+                                                type: "text",
+                                                text: `**Model fallback:** ${fallbackNotice}`,
+                                            },
                                         },
-                                    },
-                                });
+                                    });
+                                }
                                 if (persistent) {
                                     await this.syncModelAfterRefusalFallback(params.sessionId, session, message.fallback_model);
                                 }
@@ -2498,6 +2580,8 @@ export class ClaudeAcpAgent {
                         // user-turn lifecycle (stop reason, settles, failActive,
                         // slash-command output forwarding), though their cost is real.
                         const isAutonomousResult = message.origin != null && AUTONOMOUS_RESULT_ORIGINS.has(message.origin.kind);
+                        const pendingExitPlanModeInterruption = session.pendingExitPlanModeInterruption;
+                        const pendingExitPlanContextReset = session.pendingExitPlanContextReset;
                         try {
                             // Reconcile the Fast mode toggle with the SDK's reported state.
                             // Gated to user-driven turns like every other side effect below;
@@ -2650,7 +2734,10 @@ export class ClaudeAcpAgent {
                                 });
                             }
                             if (session.cancelled) {
+                                session.pendingExitPlanModeInterruption = undefined;
+                                session.pendingExitPlanContextReset = undefined;
                                 if (!isAutonomousResult) {
+                                    await clearFailuresFromEarlierTurns();
                                     stopReason = "cancelled";
                                 }
                                 break;
@@ -2686,6 +2773,37 @@ export class ClaudeAcpAgent {
                                 }
                                 break;
                             }
+                            await clearFailuresFromEarlierTurns();
+                            // `interrupt: true` is required to make "No, keep planning"
+                            // terminate the ACP turn. Claude represents that intentional
+                            // interrupt as an error-shaped diagnostic, so translate only a
+                            // diagnostic causally paired with the recorded ExitPlanMode
+                            // permission response.
+                            const diagnostic = executionDiagnostic(message);
+                            if (pendingExitPlanModeInterruption &&
+                                pendingExitPlanModeInterruption.toolResultSeen &&
+                                message.is_error &&
+                                diagnostic &&
+                                /(?:^|\s)result_type=user(?:\s|$)/.test(diagnostic) &&
+                                /(?:^|\s)stop_reason=tool_use(?:\s|$)/.test(diagnostic)) {
+                                session.pendingExitPlanModeInterruption = undefined;
+                                if (pendingExitPlanContextReset &&
+                                    pendingExitPlanContextReset.toolUseId ===
+                                        pendingExitPlanModeInterruption.toolUseId) {
+                                    await this.exitPlan.restart(params.sessionId, session, pendingExitPlanContextReset);
+                                    return;
+                                }
+                                stopReason = "cancelled";
+                                settleOrDefer({ stopReason: "cancelled", usage: sessionUsage(session) });
+                                break;
+                            }
+                            if (pendingExitPlanModeInterruption) {
+                                // This result ended the interrupted cycle without the exact
+                                // correlated cancellation shape. Never carry its marker into
+                                // a later turn, whether or not the tool result was observed.
+                                session.pendingExitPlanModeInterruption = undefined;
+                                session.pendingExitPlanContextReset = undefined;
+                            }
                             // A refusal can arrive on any result subtype (and may even set
                             // is_error), so handle it before the subtype switch — otherwise the
                             // is_error throw below would surface it as an internal error. The
@@ -2722,10 +2840,15 @@ export class ClaudeAcpAgent {
                                 settleOrDefer({ stopReason: "end_turn", usage: sessionUsage(session) });
                                 break;
                             }
+                            if (!message.is_error && lastAssistantModel !== null) {
+                                const activeTurnId = session.activeTurn?.promptUuid;
+                                await sessionFailures.clear((failure) => failure.recoveryPolicy === "real_model_success" ||
+                                    (failure.severity === "warning" && failure.turnId === activeTurnId));
+                            }
                             switch (message.subtype) {
                                 case "success": {
                                     if (message.result.includes("Please run /login")) {
-                                        failActive(RequestError.authRequired());
+                                        await failActiveWithSessionFailure("auth_required", RequestError.authRequired(), message.result);
                                         break;
                                     }
                                     if (message.stop_reason === "max_tokens") {
@@ -2733,7 +2856,7 @@ export class ClaudeAcpAgent {
                                         break;
                                     }
                                     if (message.is_error) {
-                                        failActive(RequestError.internalError(errorKindData(lastAssistantError), message.result));
+                                        await failActiveWithSessionFailure(providerFailureCategory(lastAssistantError, lastAssistantWasUsageLimit), internalErrorForClient(errorKindData(lastAssistantError), message.result), lastAssistantFailureTitle ?? message.result);
                                         break;
                                     }
                                     // The result text is forwarded in two cases. Local-only
@@ -2769,17 +2892,29 @@ export class ClaudeAcpAgent {
                                         break;
                                     }
                                     if (message.is_error) {
-                                        failActive(RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                        await failActiveWithSessionFailure(providerFailureCategory(lastAssistantError, lastAssistantWasUsageLimit), internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype), lastAssistantFailureTitle ?? (message.errors.join(", ") || message.subtype));
                                         break;
                                     }
                                     stopReason = "end_turn";
                                     break;
                                 }
                                 case "error_max_budget_usd":
+                                    if (message.is_error) {
+                                        await failActiveWithSessionFailure("budget_exhausted", internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype), message.errors.join(", ") || message.subtype);
+                                        break;
+                                    }
+                                    stopReason = "max_turn_requests";
+                                    break;
                                 case "error_max_turns":
+                                    if (message.is_error) {
+                                        await failActiveWithSessionFailure("context_exhausted", internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype), message.errors.join(", ") || message.subtype);
+                                        break;
+                                    }
+                                    stopReason = "max_turn_requests";
+                                    break;
                                 case "error_max_structured_output_retries":
                                     if (message.is_error) {
-                                        failActive(RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                        await failActiveWithSessionFailure("provider_error", internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype), message.errors.join(", ") || message.subtype);
                                         break;
                                     }
                                     stopReason = "max_turn_requests";
@@ -2917,6 +3052,7 @@ export class ClaudeAcpAgent {
                             const nextUsage = totalTokens(lastAssistantUsage);
                             if (nextUsage !== lastAssistantTotalUsage) {
                                 lastAssistantTotalUsage = nextUsage;
+                                session.contextUsedTokens = nextUsage;
                                 await sendUpdate({
                                     sessionId: params.sessionId,
                                     update: {
@@ -3053,6 +3189,11 @@ export class ClaudeAcpAgent {
                         if (message.type === "assistant" && message.parent_tool_use_id === null) {
                             lastAssistantUsage = snapshotFromUsage(message.message.usage);
                             lastAssistantTotalUsage = totalTokens(lastAssistantUsage);
+                            session.contextUsedTokens = lastAssistantTotalUsage;
+                            lastAssistantWasUsageLimit = isSyntheticUsageLimitMessage(message.message);
+                            if (message.error || lastAssistantWasUsageLimit) {
+                                lastAssistantFailureTitle = assistantMessageText(message.message);
+                            }
                             if (message.message.model && message.message.model !== "<synthetic>") {
                                 lastAssistantModel = message.message.model;
                             }
@@ -3111,7 +3252,18 @@ export class ClaudeAcpAgent {
                             break;
                         }
                         if (message.type === "assistant" && isSyntheticLoginMessage(message.message)) {
-                            failActive(RequestError.authRequired());
+                            await failActiveWithSessionFailure("auth_required", RequestError.authRequired(), assistantMessageText(message.message));
+                            break;
+                        }
+                        // AIR receives this provider condition on the terminal prompt
+                        // response as a typed failure whose title is the exact assistant
+                        // error text captured above. Do not duplicate that text as an
+                        // ordinary assistant message; legacy clients retain the historical
+                        // transcript behavior.
+                        if (message.type === "assistant" &&
+                            message.parent_tool_use_id === null &&
+                            (message.error || isSyntheticUsageLimitMessage(message.message)) &&
+                            supportsAirSessionFailures(this.clientCapabilities)) {
                             break;
                         }
                         let content;
@@ -3188,6 +3340,7 @@ export class ClaudeAcpAgent {
                         else {
                             content = message.message.content;
                         }
+                        const acceptedPlanToolUseId = observeExitPlanToolResults(message, content, session);
                         for (const notification of toAcpNotifications(content, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
                             clientCapabilities: this.clientCapabilities,
                             parentToolUseId: message.parent_tool_use_id,
@@ -3206,7 +3359,7 @@ export class ClaudeAcpAgent {
                             // filtered out of `content` above; blocks that do pass through
                             // (e.g. a subagent image) carry the stamped parentToolUseId
                             // meta and are excluded there.
-                            await sendUpdate(notification);
+                            await sendUpdate(acceptedPlanToolResult(notification, acceptedPlanToolUseId));
                         }
                         break;
                     }
@@ -3273,13 +3426,26 @@ export class ClaudeAcpAgent {
                         }
                         break;
                     }
-                    // `conversation_reset` (from `/clear`, plan-mode exit, fresh-session
-                    // flows) is safe to drop: turn lifecycle here is driven by
-                    // results/idle, and the client owns its own transcript view.
+                    case "conversation_reset": {
+                        // The SDK has switched to a fresh conversation, whose Task* IDs
+                        // and task store are independent of the previous transcript.
+                        // Clear both the in-memory snapshot and the client's visible plan
+                        // before any follow-up prompt can republish stale tasks.
+                        session.taskState.clear();
+                        await this.publishTaskPlan(params.sessionId, session.taskState);
+                        // A reset mounts a fresh transcript (`new_conversation_id`), so our
+                        // cached title no longer describes the session: drop it and
+                        // re-evaluate at the next turn-end.
+                        session.titles.reset();
+                        break;
+                    }
                     case "tool_use_summary":
-                    case "auth_status":
                     case "prompt_suggestion":
-                    case "conversation_reset":
+                        break;
+                    case "auth_status":
+                        if (!message.isAuthenticating && message.error === undefined) {
+                            await sessionFailures.clear((failure) => failure.kind === "auth_required");
+                        }
                         break;
                     default:
                         unreachable(message, this.logger);
@@ -3308,6 +3474,19 @@ export class ClaudeAcpAgent {
                     message.includes("process exited with") ||
                     message.includes("process terminated by signal") ||
                     message.includes("Failed to write to process stdin"));
+            if (supportsAirSessionFailures(this.clientCapabilities) && session.activeTurn) {
+                if (!isHeldOpen(session.activeTurn)) {
+                    await failActiveWithSessionFailure("transport_lost", internalErrorForClient({ errorKind: "transport_lost" }));
+                }
+                else {
+                    // The held turn keeps its recorded PromptResponse outcome, while the
+                    // exhausted Query makes the session independently unrecoverable.
+                    await publishSessionFailure("transport_lost", { turnScoped: false });
+                }
+            }
+            else {
+                await publishSessionFailure("transport_lost", { turnScoped: false });
+            }
             // Either way the query iterator is finished and the consumer is exiting,
             // so release its resources via closeQueryStream (idempotent). A process
             // death is unrecoverable, so additionally evict the session so the client
@@ -3321,7 +3500,9 @@ export class ClaudeAcpAgent {
             }
             else {
                 this.logger.error(`Session ${params.sessionId}: query stream error: ${message}`);
-                failAllTurns(error);
+                failAllTurns(supportsAirSessionFailures(this.clientCapabilities)
+                    ? internalErrorForClient({ errorKind: "transport_lost" })
+                    : error);
                 this.closeQueryStream(session);
             }
         }
@@ -3351,6 +3532,7 @@ export class ClaudeAcpAgent {
         }
     }
     async cancel(params) {
+        this.exitPlan.cancel(params.sessionId);
         const session = this.sessions[params.sessionId];
         if (!session) {
             return;
@@ -3364,6 +3546,9 @@ export class ClaudeAcpAgent {
         if (session.queryRecreateInFlight) {
             await session.queryRecreateInFlight;
         }
+        session.cancelled = true;
+        session.pendingExitPlanModeInterruption = undefined;
+        session.pendingExitPlanContextReset = undefined;
         // The stream already ended (see closeQueryStream): every in-flight turn was
         // settled when it closed, and there is no live query to interrupt. Calling
         // query.interrupt() on a finished iterator could reject and surface from
@@ -3371,7 +3556,6 @@ export class ClaudeAcpAgent {
         if (session.queryClosed) {
             return;
         }
-        session.cancelled = true;
         // A priority steer may still be queued in the SDK when cancellation
         // settles its owning turn. Its later echo matches no live turn, and its
         // result must be skipped rather than promoted onto the next prompt.
@@ -3395,6 +3579,7 @@ export class ClaudeAcpAgent {
         if (session.turnQueue) {
             for (const turn of session.turnQueue) {
                 if (turn !== session.activeTurn && !turn.settled) {
+                    this.finishFileChangeAudit(session, turn, "cancelled");
                     turn.settled = true;
                     // Deliberately no `usage`: a queued turn never ran, so the session
                     // accumulator (the active turn's tally) is not its spend.
@@ -3414,7 +3599,9 @@ export class ClaudeAcpAgent {
             // never see lifecycle frames, so commandStarted/commandFinished stay
             // unset and every turn takes the plain-seed path below).
             for (const turn of orphanedTurns) {
-                if (turn.commandFinished === "completed" || turn.commandFinished === "discarded") {
+                if (turn.commandFinished === "completed" ||
+                    turn.commandFinished === "discarded" ||
+                    turn.commandFinished === "refused") {
                     // The command already finished SDK-side and its terminal frame was
                     // consumed while the turn sat queued — nothing is left to skip, and
                     // a seeded entry would never drain.
@@ -3456,6 +3643,7 @@ export class ClaudeAcpAgent {
         {
             const active = session.activeTurn;
             if (isHeldOpen(active)) {
+                this.finishFileChangeAudit(session, active, "cancelled");
                 active.settled = true;
                 // Mirror settleActive's invariants (it is consumer-scoped and
                 // unreachable from here): disarm the backstop — none should be
@@ -3639,27 +3827,19 @@ export class ClaudeAcpAgent {
         return {};
     }
     async setSessionMode(params) {
-        const session = this.sessions[params.sessionId];
-        if (!session) {
-            throw new Error("Session not found");
-        }
         // A lazy Thinking recreate may be swapping the session's query right now;
         // join it (mirroring prompt()) so `setPermissionMode` below lands on the
         // replacement query after cutover instead of an about-to-close one — and
         // so the mode isn't silently dropped from a query built from the
         // pre-await state snapshot. Safe: `recreateSessionQuery` never rejects.
-        if (session.queryRecreateInFlight) {
+        // The session-not-found and SESSION_ENDED guards the fork inlined here now
+        // live in `SessionModeManager.requireOpenSession`, which raises the same
+        // errors, so they are not duplicated in front of the delegation below.
+        const session = this.sessions[params.sessionId];
+        if (session?.queryRecreateInFlight) {
             await session.queryRecreateInFlight;
         }
-        // The SDK query stream already ended (see closeQueryStream); the session is
-        // a husk and `query.setPermissionMode` below would act on a closed query.
-        // Fail with the same clear message prompt()/cancel() give for a dead stream.
-        if (session.queryClosed) {
-            throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
-        }
-        await this.applySessionMode(params.sessionId, params.modeId);
-        await this.updateConfigOption(params.sessionId, MODE_CONFIG_ID, params.modeId);
-        return {};
+        return this.sessionModes.setSessionMode(params);
     }
     async setSessionConfigOption(params) {
         const session = this.sessions[params.sessionId];
@@ -3687,10 +3867,9 @@ export class ClaudeAcpAgent {
         if (!option) {
             throw new Error(`Unknown config option: ${params.configId}`);
         }
-        // Fast mode is always emitted as an "on"/"off" select, but a native
-        // boolean set value is still accepted for compatibility (R2.3), so it
-        // bypasses the string-only validation the select-style options below
-        // rely on.
+        // Fast mode carries a boolean value (for Clients that opted into boolean
+        // config options) or the "on"/"off" select fallback, so it bypasses the
+        // string-only validation the select-style options below rely on.
         if (params.configId === FAST_MODE_CONFIG_ID) {
             await this.applyFastMode(session, resolveFastModeEnabled(params));
             return { configOptions: session.configOptions };
@@ -3759,15 +3938,10 @@ export class ClaudeAcpAgent {
         // Use the canonical option value so downstream code always receives the
         // model ID rather than the caller-supplied alias.
         const resolvedValue = validValue.value;
+        let effectiveValue = resolvedValue;
         if (params.configId === MODE_CONFIG_ID) {
-            await this.applySessionMode(params.sessionId, resolvedValue);
-            await this.client.sessionUpdate({
-                sessionId: params.sessionId,
-                update: {
-                    sessionUpdate: "current_mode_update",
-                    currentModeId: resolvedValue,
-                },
-            });
+            effectiveValue = await this.sessionModes.selectMode(params.sessionId, resolvedValue);
+            await this.sessionModes.publishCurrent(params.sessionId, effectiveValue);
         }
         else if (params.configId === MODEL_CONFIG_ID) {
             await this.sessions[params.sessionId].query.setModel(resolvedValue);
@@ -3775,50 +3949,41 @@ export class ClaudeAcpAgent {
         // Effort SDK sync is handled inside applyConfigOptionValue so that direct
         // effort changes and effort changes induced by a model switch go through
         // the same path.
-        await this.applyConfigOptionValue(params.sessionId, session, params.configId, resolvedValue);
+        await this.applyConfigOptionValue(params.sessionId, session, params.configId, effectiveValue);
         return { configOptions: session.configOptions };
     }
-    async applySessionMode(sessionId, modeId) {
-        switch (modeId) {
-            case "auto":
-            case "default":
-            case "acceptEdits":
-            case "bypassPermissions":
-            case "dontAsk":
-            case "plan":
-                break;
-            default:
-                throw new Error("Invalid Mode");
-        }
-        const session = this.sessions[sessionId];
-        if (!session) {
-            throw new Error("Session not found");
-        }
-        if (!session.modes.availableModes.some((mode) => mode.id === modeId)) {
-            throw new Error(`Mode ${modeId} is not available in this session`);
-        }
-        try {
-            await session.query.setPermissionMode(modeId);
-        }
-        catch (error) {
-            if (error instanceof Error) {
-                if (!error.message) {
-                    error.message = "Invalid Mode";
-                }
-                throw error;
-            }
-            else {
-                // eslint-disable-next-line preserve-caught-error
-                throw new Error("Invalid Mode");
-            }
-        }
-    }
     async replaySessionHistory(sessionId) {
         const toolUseCache = {};
         const messages = await getSessionMessages(sessionId);
-        const forwardSubagentText = this.sessions[sessionId]?.forwardSubagentText ??
-            supportsSubagentTranscript(this.clientCapabilities);
+        const session = this.sessions[sessionId];
+        const forwardSubagentText = session?.forwardSubagentText ?? supportsSubagentTranscript(this.clientCapabilities);
+        const supportsTypedFailures = supportsAirSessionFailures(this.clientCapabilities);
+        const activeUsageLimit = supportsTypedFailures ? activeUsageLimitMessage(messages) : undefined;
+        const sessionFailures = session && supportsTypedFailures
+            ? new SessionFailureController({
+                sessionId,
+                state: session.sessionFailureState,
+                capabilities: this.clientCapabilities,
+                isCurrent: () => this.sessions[sessionId] === session,
+                sendUpdate: (notification) => this.client.sessionUpdate(notification),
+                logger: this.logger,
+            })
+            : undefined;
+        let replayTurnId;
+        // Stop-hook additionalContext is persisted as an internal user message.
+        // Once that marker (or the internal tool itself) appears, suppress the
+        // whole audit exchange until its tool result. This also hides a disobedient
+        // model's separate prose message, while an ordinary next user prompt safely
+        // ends an incomplete audit lane.
+        let replayingFileChangeAudit = false;
+        const replayFileChangeAuditToolUseIds = new Set();
         for (const message of messages) {
+            if (message.type === "user" &&
+                message.parent_tool_use_id === null &&
+                typeof message.uuid === "string" &&
+                message.uuid.length > 0) {
+                replayTurnId = message.uuid;
+            }
             // Backfill the ACP messageId -> SDK uuid mapping for messages we didn't
             // observe live (resumed/loaded sessions), so rewind/resume can translate
             // a client-supplied id without an extra getSessionMessages read. Not read
@@ -3834,6 +3999,21 @@ export class ClaudeAcpAgent {
             if (message.type === "assistant" && isSyntheticLoginMessage(message.message)) {
                 continue;
             }
+            // Capable clients saw every synthetic usage-limit message as a typed
+            // failure live, so replay it at the same transcript position. The
+            // preceding persisted user uuid is the live prompt uuid and therefore
+            // recreates the same incident identity. Only the latest limit not
+            // followed by a real model answer remains active internally.
+            if (sessionFailures &&
+                message.type === "assistant" &&
+                message.parent_tool_use_id === null &&
+                isSyntheticUsageLimitMessage(message.message)) {
+                const title = assistantMessageText(message.message);
+                if (title) {
+                    await sessionFailures.restore(replayTurnId ? `${replayTurnId}:error` : `${sessionId}:history-error:${message.uuid}`, "quota_exhausted", title, message.uuid === activeUsageLimit?.uuid);
+                }
+                continue;
+            }
             // @ts-expect-error - untyped in SDK but we handle all of these
             let content = message.message.content;
             const parentToolUseId = parentToolUseIdOf(message);
@@ -3846,6 +4026,57 @@ export class ClaudeAcpAgent {
                 if (content === null)
                     continue;
             }
+            const auditBlocks = Array.isArray(content)
+                ? content.filter((block) => typeof block === "object" && block !== null)
+                : [];
+            const hasFileChangeAuditMarker = (typeof content === "string" && containsFileChangeAuditMarker(content)) ||
+                auditBlocks.some((block) => typeof block.text === "string" && containsFileChangeAuditMarker(block.text));
+            const fileChangeAuditToolUseIds = auditBlocks.flatMap((block) => (block.type === "tool_use" ||
+                block.type === "server_tool_use" ||
+                block.type === "mcp_tool_use") &&
+                typeof block.name === "string" &&
+                isFileChangeAuditTool(block.name) &&
+                typeof block.id === "string"
+                ? [block.id]
+                : []);
+            const replayMessageRole = message.message
+                ?.role;
+            if (hasFileChangeAuditMarker || fileChangeAuditToolUseIds.length > 0) {
+                replayingFileChangeAudit = true;
+                for (const toolUseId of fileChangeAuditToolUseIds) {
+                    replayFileChangeAuditToolUseIds.add(toolUseId);
+                }
+                continue;
+            }
+            if (replayingFileChangeAudit) {
+                const toolResultIds = auditBlocks.flatMap((block) => (block.type === "tool_result" || block.type === "mcp_tool_result") &&
+                    typeof block.tool_use_id === "string"
+                    ? [block.tool_use_id]
+                    : []);
+                let completedReport = false;
+                for (const toolUseId of toolResultIds) {
+                    if (replayFileChangeAuditToolUseIds.delete(toolUseId))
+                        completedReport = true;
+                }
+                if (completedReport && replayFileChangeAuditToolUseIds.size === 0) {
+                    replayingFileChangeAudit = false;
+                    continue;
+                }
+                // A denied attempt to call another tool is still part of the hidden
+                // lane. Its result must not end replay suppression before the report.
+                if (toolResultIds.length > 0) {
+                    continue;
+                }
+                // The next real user prompt is already represented by the client and
+                // starts a new turn; do not let a missing audit result hide it or the
+                // rest of the replay.
+                if (replayMessageRole === "user") {
+                    replayingFileChangeAudit = false;
+                }
+                else {
+                    continue;
+                }
+            }
             for (const notification of toAcpNotifications(
             // @ts-expect-error - untyped in SDK but we handle all of these
             content, 
@@ -3870,23 +4101,52 @@ export class ClaudeAcpAgent {
         const response = await this.client.writeTextFile(params);
         return response;
     }
+    /** Mark a client request as blocking on user input for exactly the lifetime
+     *  of its promise. Steering consults this session-local count synchronously,
+     *  so a message arriving while any permission/elicitation card is open uses
+     *  non-interrupting SDK delivery. The decrement sits in `finally` (and is
+     *  clamped at zero), so accepted, declined, cancelled, aborted and failed
+     *  requests all settle the count — a request that ends by throwing must not
+     *  pin the session at `later` for the rest of its life. */
+    async withPendingUserInput(sessionId, request) {
+        const session = this.sessions[sessionId];
+        if (!session)
+            return request();
+        session.pendingUserInputCount = (session.pendingUserInputCount ?? 0) + 1;
+        try {
+            return await request();
+        }
+        finally {
+            // Decrement the SAME object the increment ran on, not a fresh
+            // `this.sessions[sessionId]` lookup: a session replaced mid-request would
+            // otherwise be charged for a request it never made. Both the clamp and
+            // the `?? 1` land such a replacement's own count on 0, never below it.
+            session.pendingUserInputCount = Math.max(0, (session.pendingUserInputCount ?? 1) - 1);
+        }
+    }
     /** Forward a permission request to the client, wiring the tool call's
      *  `signal` through as a `cancellationSignal`. When the turn is cancelled
      *  while the client's prompt is still open the signal aborts, the SDK sends
-     *  `$/cancel_request`, and the client settles the request (a `cancelled`
-     *  outcome or a `requestCancelled` rejection). Either way we surface the same
-     *  "Tool use aborted" the callers already expect, so a cancelled dialog no
-     *  longer leaves the `await` hanging. */
+     *  `$/cancel_request`, and our local abort race settles even if the client
+     *  ignores it. A `cancelled` outcome, request rejection, and local abort all
+     *  surface the same "Tool use aborted" the callers already expect. */
     async requestPermissionFromClient(params, toolName, signal, parentToolUseId) {
+        if (signal.aborted)
+            throw new Error("Tool use aborted");
         // The SDK may invoke `canUseTool` (and therefore this permission request)
         // before the assistant message's tool_use block streams to us. Some ACP clients
         // expect the `tool_call` a permission request references to already exist,
         // so emit it now if it hasn't been sent yet. The streamed tool_use chunk
         // later refines it with a `tool_call_update` rather than emitting a
         // duplicate (see `emittedToolCalls` in `toAcpNotifications`).
-        await this.ensureToolCallEmitted(params.sessionId, toolName, params.toolCall.toolCallId, params.toolCall.rawInput, parentToolUseId);
+        await this.ensureToolCallEmitted(params.sessionId, toolName, params.toolCall.toolCallId, params.toolCall.rawInput, parentToolUseId, signal);
+        if (signal.aborted)
+            throw new Error("Tool use aborted");
+        // Do not rely on every ACP client settling requestPermission after the
+        // cancellation signal. The local race guarantees that Claude's tool call
+        // is released even when an older or broken client ignores $/cancel_request.
         try {
-            return await this.client.requestPermission(params, signal);
+            return await this.withPendingUserInput(params.sessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
         }
         catch (error) {
             if (signal.aborted) {
@@ -3907,7 +4167,7 @@ export class ClaudeAcpAgent {
      *  are resolved at tool_result time instead (see `toAcpNotifications`).
      *  `parentToolUseId` attributes a subagent's tool call to the Agent/Task call
      *  that spawned it, matching the streamed path's `_meta`. */
-    async ensureToolCallEmitted(sessionId, toolName, toolCallId, toolInput, parentToolUseId) {
+    async ensureToolCallEmitted(sessionId, toolName, toolCallId, toolInput, parentToolUseId, signal) {
         const session = this.sessions[sessionId];
         if (!session) {
             return;
@@ -3927,10 +4187,20 @@ export class ClaudeAcpAgent {
                 },
             };
         }
-        await this.client.sessionUpdate({ sessionId, update });
+        try {
+            const emission = this.client.sessionUpdate({ sessionId, update });
+            await (signal ? raceWithAbort(emission, signal) : emission);
+        }
+        catch (error) {
+            // The set is also the de-duplication guard for the later streamed
+            // tool_use. Keep it truthful: if emission failed, that path must still
+            // be allowed to publish the tool call instead of refining a phantom one.
+            session.emittedToolCalls.delete(toolCallId);
+            throw error;
+        }
     }
     canUseTool(sessionId) {
-        return async (toolName, toolInput, { signal, suggestions, toolUseID, agentID, matchedAskRule }) => {
+        return async (toolName, toolInput, { signal, suggestions, toolUseID, agentID, matchedAskRule, blockedPath, decisionReason, title, displayName, description, }) => {
             const supportsTerminalOutput = this.clientCapabilities?._meta?.["terminal_output"] === true;
             const session = this.sessions[sessionId];
             if (!session) {
@@ -3939,6 +4209,26 @@ export class ClaudeAcpAgent {
                     message: "Session not found",
                 };
             }
+            const fileChangeAudit = session.activeTurn?.fileChangeAudit;
+            if (isFileChangeAuditReportPhase(fileChangeAudit)) {
+                // The hidden continuation is an audit-only lane: it may submit the
+                // wrapper-owned report, but it must not run another command after the
+                // user-visible answer has already completed.
+                if (isFileChangeAuditTool(toolName) && fileChangeAudit?.phase === "collecting") {
+                    return { behavior: "allow", updatedInput: toolInput };
+                }
+                return {
+                    behavior: "deny",
+                    message: "Only the internal file-change report is allowed during the audit.",
+                };
+            }
+            // The tool is intentionally unusable outside a negotiated audit turn.
+            if (isFileChangeAuditTool(toolName)) {
+                return {
+                    behavior: "deny",
+                    message: "No file-change report was requested for this turn.",
+                };
+            }
             // When the tool call originates inside a subagent, attribute the eagerly
             // emitted tool_call (and the permission request itself) to the Agent/Task
             // tool call that spawned the subagent, mirroring the streamed subagent
@@ -3963,155 +4253,81 @@ export class ClaudeAcpAgent {
             if (toolName === "AskUserQuestion" && this.clientCapabilities?.elicitation?.form) {
                 // Like permission requests, the elicitation references this toolUseID, so
                 // make sure the tool_call has surfaced to the client before we send it.
-                await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput, parentToolUseId);
+                await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput, parentToolUseId, signal);
                 return this.handleAskUserQuestion(sessionId, toolInput, toolUseID, signal);
             }
-            if (toolName === "ExitPlanMode") {
-                const optionsAll = [
-                    { kind: "allow_always", name: 'Yes, and use "auto" mode', optionId: "auto" },
-                    {
-                        kind: "allow_always",
-                        name: "Yes, and auto-accept edits",
-                        optionId: "acceptEdits",
-                    },
-                    { kind: "allow_once", name: "Yes, and manually approve edits", optionId: "default" },
-                    { kind: "reject_once", name: "No, keep planning", optionId: "plan" },
-                ];
-                if (ALLOW_BYPASS) {
-                    optionsAll.unshift({
-                        kind: "allow_always",
-                        name: "Yes, and bypass permissions",
-                        optionId: "bypassPermissions",
-                    });
-                }
-                // Filter against the session's currently-advertised modes so we never
-                // present options the active model can't honor (e.g. `auto` on Haiku).
-                // `bypassPermissions` is already covered by `availableModes` via
-                // `buildAvailableModes`/`ALLOW_BYPASS`. The `plan` option is a
-                // "keep planning" reject path; it's always present in `availableModes`.
-                const options = optionsAll.filter((o) => session.modes.availableModes.some((m) => m.id === o.optionId));
-                const response = await this.requestPermissionFromClient({
-                    options,
-                    sessionId,
-                    toolCall: {
-                        toolCallId: toolUseID,
-                        rawInput: toolInput,
-                        ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
-                        // `claudeCode` metas always carry `toolName` (see ToolUpdateMeta),
-                        // so clients can rely on one shape everywhere.
-                        ...(parentToolUseId
-                            ? { _meta: { claudeCode: { toolName, parentToolUseId } } }
-                            : {}),
-                    },
-                }, toolName, signal, parentToolUseId);
-                if (signal.aborted || response.outcome?.outcome === "cancelled") {
-                    throw new Error("Tool use aborted");
-                }
-                const selectedMode = response.outcome?.outcome === "selected" ? response.outcome.optionId : undefined;
-                const selectedModeWasOffered = options.some((option) => option.optionId === selectedMode);
-                if (selectedModeWasOffered &&
-                    (selectedMode === "default" ||
-                        selectedMode === "acceptEdits" ||
-                        selectedMode === "auto" ||
-                        selectedMode === "bypassPermissions")) {
-                    await this.client.sessionUpdate({
-                        sessionId,
-                        update: {
-                            sessionUpdate: "current_mode_update",
-                            currentModeId: selectedMode,
-                        },
-                    });
-                    await this.updateConfigOption(sessionId, MODE_CONFIG_ID, selectedMode);
-                    return {
-                        behavior: "allow",
-                        updatedInput: toolInput,
-                        updatedPermissions: suggestions ?? [
-                            { type: "setMode", mode: selectedMode, destination: "session" },
-                        ],
-                    };
-                }
-                else {
-                    return {
-                        behavior: "deny",
-                        message: "User rejected request to exit plan mode.",
-                    };
-                }
-            }
-            // In bypass mode the CLI skips permission checks itself; the asks that
-            // still reach canUseTool are the ones it insists on prompting for even
-            // under --dangerously-skip-permissions. Keep auto-allowing those —
-            // bypass means bypass — EXCEPT rule-forced asks (`matchedAskRule`): the
-            // user explicitly configured a permissions.ask rule for this tool, and
-            // the SDK's guidance is that hosts running auto-approval must treat such
-            // asks as a human prompt. Fall through to the normal request below.
-            if (session.modes.currentModeId === "bypassPermissions" && !matchedAskRule) {
-                return {
-                    behavior: "allow",
-                    updatedInput: toolInput,
-                    updatedPermissions: suggestions ?? [
-                        { type: "addRules", rules: [{ toolName }], behavior: "allow", destination: "session" },
-                    ],
+            // Do not auto-allow here based on the session's advertised mode. Claude
+            // Code applies bypassPermissions before invoking canUseTool; a request
+            // that still reaches this callback is deliberately bypass-immune (for
+            // example a safety check, a tool requiring user interaction, or an
+            // explicit ask rule). Re-applying bypass in the host would erase that
+            // provider safety decision.
+            const durableChangeSet = normalizeDurablePermissionChangeSet(suggestions, matchedAskRule !== undefined);
+            const presentation = buildClaudePermissionPresentation({
+                toolName,
+                input: toolInput,
+                toolUseID,
+                cwd: session.cwd,
+                supportsTerminalOutput,
+                blockedPath,
+                title,
+                displayName,
+                description,
+                decisionReason,
+            });
+            if (parentToolUseId) {
+                presentation.toolCall._meta = {
+                    claudeCode: { toolName, parentToolUseId },
                 };
             }
+            const permissionOptions = buildClaudePermissionOptions({
+                toolName,
+                displayName,
+                input: toolInput,
+                cwd: session.cwd,
+                durableChangeSet,
+                allowPersistentOptions: matchedAskRule === undefined,
+                availableModes: this.sessionModes.availableModeIds(session.modes),
+                contextUsedPercent: session.contextUsedTokens === undefined || session.contextWindowSize <= 0
+                    ? undefined
+                    : Math.max(0, Math.min(100, Math.round((session.contextUsedTokens / session.contextWindowSize) * 100))),
+            });
             const response = await this.requestPermissionFromClient({
-                options: [
-                    { kind: "reject_once", name: "Deny", optionId: "reject" },
-                    { kind: "allow_once", name: "Allow Once", optionId: "allow" },
-                    {
-                        // The label discloses the scope for clients that render only the
-                        // option name; `_meta.permission` carries the same commitment in
-                        // the structured upstream form. See `describeAlwaysAllow`.
-                        kind: "allow_always",
-                        name: describeAlwaysAllow(suggestions, toolName),
-                        optionId: "allow_always",
-                        _meta: {
-                            permission: permissionMetadataForAlwaysAllow(suggestions, toolName),
-                        },
-                    },
-                ],
+                ...presentation,
+                options: permissionOptions,
                 sessionId,
-                toolCall: {
-                    toolCallId: toolUseID,
-                    rawInput: toolInput,
-                    ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
-                    // `claudeCode` metas always carry `toolName` (see ToolUpdateMeta),
-                    // so clients can rely on one shape everywhere.
-                    ...(parentToolUseId
-                        ? { _meta: { claudeCode: { toolName, parentToolUseId } } }
-                        : {}),
-                },
             }, toolName, signal, parentToolUseId);
-            if (signal.aborted || response.outcome?.outcome === "cancelled") {
+            if (signal.aborted)
                 throw new Error("Tool use aborted");
+            const decodedPermission = decodeClaudePermissionResponse(response, toolName, toolInput, toolUseID, permissionOptions, durableChangeSet);
+            let permissionResult = decodedPermission.permissionResult;
+            const autoFallback = this.sessionModes.applyPermissionFallback(session, permissionResult);
+            permissionResult = autoFallback.permissionResult;
+            if (autoFallback.fallbackApplied) {
+                await this.sessionModes.publishFallbackWarning(sessionId, session);
             }
-            if (response.outcome?.outcome === "selected" &&
-                (response.outcome.optionId === "allow" || response.outcome.optionId === "allow_always")) {
-                // If Claude Code has suggestions, it will update their settings already
-                if (response.outcome.optionId === "allow_always") {
-                    return {
-                        behavior: "allow",
-                        updatedInput: toolInput,
-                        updatedPermissions: suggestions ?? [
-                            {
-                                type: "addRules",
-                                rules: [{ toolName }],
-                                behavior: "allow",
-                                destination: "session",
-                            },
-                        ],
-                    };
-                }
-                return {
-                    behavior: "allow",
-                    updatedInput: toolInput,
+            const clearContextMode = decodedPermission.contextResetMode
+                ? this.sessionModes.effectiveMode(session, decodedPermission.contextResetMode)
+                : undefined;
+            if (toolName === "ExitPlanMode" && clearContextMode) {
+                const plan = typeof toolInput.plan === "string" ? toolInput.plan.trim() : "";
+                if (!plan)
+                    throw new Error("ExitPlanMode clear-context selection requires a plan");
+                session.pendingExitPlanContextReset = {
+                    toolUseId: toolUseID,
+                    plan,
+                    mode: clearContextMode,
                 };
             }
-            else {
-                return {
-                    behavior: "deny",
-                    message: "User refused permission to run tool",
+            if (toolName === "ExitPlanMode" &&
+                permissionResult.behavior === "deny" &&
+                permissionResult.interrupt === true) {
+                session.pendingExitPlanModeInterruption = {
+                    toolUseId: toolUseID,
+                    toolResultSeen: false,
                 };
             }
+            return permissionResult;
         };
     }
     /**
@@ -4130,7 +4346,7 @@ export class ClaudeAcpAgent {
                 return { action: "decline" };
             }
             try {
-                const response = await this.client.unstable_createElicitation(createRequest, signal);
+                const response = await this.withPendingUserInput(sessionId, () => this.client.unstable_createElicitation(createRequest, signal));
                 if (signal.aborted) {
                     return { action: "cancel" };
                 }
@@ -4160,7 +4376,7 @@ export class ClaudeAcpAgent {
         const createRequest = askUserQuestionsToCreateRequest(questions, sessionId, toolUseID);
         let response;
         try {
-            response = await this.client.unstable_createElicitation(createRequest, signal);
+            response = await this.withPendingUserInput(sessionId, () => this.client.unstable_createElicitation(createRequest, signal));
         }
         catch (error) {
             // A cancellation we requested (signal aborted) settles as an aborted tool
@@ -4200,7 +4416,7 @@ export class ClaudeAcpAgent {
             }
             let response;
             try {
-                response = await this.client.unstable_createElicitation(refusalFallbackToCreateRequest(prompt, sessionId), signal);
+                response = await this.withPendingUserInput(sessionId, () => this.client.unstable_createElicitation(refusalFallbackToCreateRequest(prompt, sessionId), signal));
             }
             catch (error) {
                 // A cancellation we requested (signal aborted) is expected teardown;
@@ -4227,7 +4443,7 @@ export class ClaudeAcpAgent {
             sessionId,
             update: {
                 sessionUpdate: "available_commands_update",
-                availableCommands: getAvailableSlashCommands(commands),
+                availableCommands: getAvailableSlashCommands(commands, session.terminalSlashCommands),
             },
         });
     }
@@ -4246,12 +4462,11 @@ export class ClaudeAcpAgent {
     }
     async applyConfigOptionValue(sessionId, session, configId, value) {
         if (configId === MODE_CONFIG_ID) {
-            session.modes = { ...session.modes, currentModeId: value };
-            session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
+            this.sessionModes.syncConfig(session, value);
         }
         else if (configId === MODEL_CONFIG_ID) {
-            // `ModelInfo.supportsAutoMode` is the canonical SDK signal for clamping
-            // modes below; its `displayName`/`description` also let us infer the
+            // `ModelInfo.supportsAutoMode` is the canonical SDK signal for applying
+            // the Auto fallback below; its `displayName`/`description` also let us infer the
             // context window for semantic aliases (e.g. `default`) whose ID alone
             // carries no "1m" token.
             const newModelInfo = session.modelInfos.find((m) => m.value === value);
@@ -4273,41 +4488,7 @@ export class ClaudeAcpAgent {
                 session.contextWindowAuthoritative = seeded.authoritative;
             }
             session.models = { ...session.models, currentModelId: value };
-            // Recompute availableModes for the new model and clamp the current
-            // mode if the SDK no longer offers it (today: "auto" on Haiku). An
-            // unknown model (an SDK-initiated refusal fallback to a model outside
-            // the user's `availableModels` allowlist — user-driven switches are
-            // validated against the options first) tells us nothing about its
-            // capabilities, so keep the current modes rather than spuriously
-            // downgrading (e.g. kicking the user out of "auto" for a model that
-            // does support it).
-            const newAvailableModes = newModelInfo
-                ? buildAvailableModes(newModelInfo)
-                : session.modes.availableModes;
-            // Capture BEFORE mutating session.modes so the log message reflects
-            // the invalidated mode rather than "default".
-            const previousModeId = session.modes.currentModeId;
-            let modeDowngraded = false;
-            if (!newAvailableModes.some((m) => m.id === previousModeId)) {
-                session.modes = {
-                    availableModes: newAvailableModes,
-                    currentModeId: "default",
-                };
-                try {
-                    await session.query.setPermissionMode("default");
-                }
-                catch (err) {
-                    // Failing the entire model switch over a bookkeeping sync error is
-                    // worse UX than logging and continuing; the user explicitly asked
-                    // to change models. The next setPermissionMode from the user will
-                    // either succeed or surface a fresh error.
-                    this.logger.error(`Failed to sync permissionMode to "default" after model switch invalidated "${previousModeId}":`, err);
-                }
-                modeDowngraded = true;
-            }
-            else {
-                session.modes = { ...session.modes, availableModes: newAvailableModes };
-            }
+            const modeDowngraded = await this.sessionModes.reconcileForModel(session, newModelInfo);
             // `model_not_allowed` described the model we just left, so it must not
             // follow us onto the new one; the remaining reasons are account- or
             // environment-scoped and stay true across a switch. Either way the next
@@ -4324,6 +4505,7 @@ export class ClaudeAcpAgent {
                 // intent) when a supporting model is selected again.
                 supported: newModelInfo?.supportsFastMode ?? false,
                 enabled: session.fastModeEnabled,
+                useBooleanOption: clientSupportsBooleanConfigOptions(this.clientCapabilities),
                 disabledReason: session.fastModeDisabledReason,
             }, 
             // Thinking is model-independent: re-render the retained tri-state
@@ -4349,13 +4531,7 @@ export class ClaudeAcpAgent {
             // still precedes the caller's config_option_update so order-sensitive
             // clients update currentModeId before re-rendering the option list.
             if (modeDowngraded) {
-                await this.client.sessionUpdate({
-                    sessionId,
-                    update: {
-                        sessionUpdate: "current_mode_update",
-                        currentModeId: "default",
-                    },
-                });
+                await this.sessionModes.publishFallbackState(sessionId, session);
             }
         }
         else if (configId === AGENT_CONFIG_ID) {
@@ -4410,13 +4586,11 @@ export class ClaudeAcpAgent {
         }
     }
     /** Replace the Fast mode option in `session.configOptions` so it reflects
-     *  `enabled` (and the session's current disabled reason). A no-op when the
+     *  `enabled` (and the client's current boolean-capability). A no-op when the
      *  option isn't present, so callers must confirm the current model surfaces
-     *  it first. Rebuilds through {@link createFastModeConfigOption} — the one
-     *  source of the option's shape — so the shape can't drift from what
-     *  `buildConfigOptions` first emitted. */
+     *  it first. */
     refreshFastModeOption(session, enabled) {
-        const refreshed = createFastModeConfigOption(enabled, session.fastModeDisabledReason);
+        const refreshed = createFastModeConfigOption(enabled, clientSupportsBooleanConfigOptions(this.clientCapabilities), session.fastModeDisabledReason);
         session.configOptions = session.configOptions.map((o) => o.id === FAST_MODE_CONFIG_ID ? refreshed : o);
     }
     /** Toggle Fast mode for a session: push the SDK flag, record the user's
@@ -4813,7 +4987,10 @@ export class ClaudeAcpAgent {
         // We want to create a new session id unless it is resume,
         // but not resume + forkSession.
         let sessionId;
-        if (creationOpts.forkSession) {
+        if (creationOpts.publicSessionId) {
+            sessionId = creationOpts.publicSessionId;
+        }
+        else if (creationOpts.forkSession) {
             sessionId = randomUUID();
         }
         else if (creationOpts.resume) {
@@ -4872,6 +5049,7 @@ export class ClaudeAcpAgent {
             }
         }
         const permissionMode = resolvePermissionMode(settingsManager.getSettings().permissions?.defaultMode, this.logger);
+        const initialPermissionMode = creationOpts.permissionMode ?? permissionMode;
         // Extract options from _meta if provided
         const sessionMeta = params._meta;
         const userProvidedOptions = sessionMeta?.claudeCode?.options;
@@ -4906,6 +5084,30 @@ export class ClaudeAcpAgent {
         // below) so the TaskCreated/TaskCompleted hook callbacks can close over
         // the same Map that the streaming message handler will read from.
         const taskState = new Map();
+        // Resolve every workspace root once. The hidden report tool uses this same
+        // set for lexical path validation, and the SDK receives it below.
+        const acpAdditionalDirectories = params.additionalDirectories ?? sessionMeta?.additionalRoots ?? [];
+        const additionalDirectories = [
+            ...(userProvidedOptions?.additionalDirectories ?? []),
+            ...acpAdditionalDirectories,
+        ];
+        const fileChangeAuditSupport = supportsAgentFileChangeReport(this.clientCapabilities)
+            ? createFileChangeAuditSupport({
+                cwd: params.cwd,
+                additionalDirectories,
+                getActiveState: () => this.sessions[sessionId]?.activeTurn?.fileChangeAudit,
+                publish: async (result) => {
+                    await this.client.sessionUpdate({
+                        sessionId,
+                        update: {
+                            sessionUpdate: "session_info_update",
+                            _meta: agentFileChangeReportMeta(result),
+                        },
+                    });
+                },
+                logError: (message) => this.logger.error(message),
+            })
+            : undefined;
         // The exact env the query will be created with. Built (and the provider
         // cache key derived from it, below) in one place so the key always
         // describes the backend this query actually talks to: `providers/set`,
@@ -4913,13 +5115,36 @@ export class ClaudeAcpAgent {
         // config concurrently, so re-resolving it after any of the awaits between
         // here and the session registration could disagree with the env baked
         // into the query.
+        const resolvedProvider = this.resolveProviderConfig();
+        const providerEnv = createEnvForProvider(resolvedProvider);
+        const configuredSettings = userProvidedOptions?.settings ??
+            (modelConfig
+                ? {
+                    ...(modelConfig.modelOverrides && { modelOverrides: modelConfig.modelOverrides }),
+                    ...(modelConfig.availableModels && { availableModels: modelConfig.availableModels }),
+                }
+                : undefined);
+        // Claude Code applies env from settings.json after the subprocess env. Put
+        // an active ACP route in the programmatic settings tier too so user/project
+        // settings cannot silently restore a different ANTHROPIC_BASE_URL.
+        let settings = configuredSettings;
+        if (resolvedProvider) {
+            const baseSettings = typeof configuredSettings === "string"
+                ? JSON.parse(await fs.readFile(path.resolve(params.cwd, configuredSettings), "utf8"))
+                : configuredSettings;
+            settings = {
+                ...baseSettings,
+                apiKeyHelper: "",
+                env: { ...baseSettings?.env, ...providerEnv },
+            };
+        }
         const env = {
             ...process.env,
             ...userProvidedOptions?.env,
             // Client-managed LLM routing: `providers/set` config wins, else the
-            // legacy gateway auth request. Baked into the query at creation, so it
-            // only affects sessions started after the change (matching the RFD).
-            ...createEnvForProvider(this.resolveProviderConfig()),
+            // legacy gateway auth request. Routing is baked into the query at
+            // creation; provider updates recreate loaded queries between turns.
+            ...providerEnv,
             // Opt-in to session state events like when the agent is idle
             CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
         };
@@ -4928,6 +5153,7 @@ export class ClaudeAcpAgent {
         // SDK, so per-session `_meta` env routing and ambient process-env routing
         // are distinguished exactly as the CLI will see them.
         const providerCacheKey = providerCacheKeyFor(env);
+        this.logger.log(`[session/query] sessionId=${sessionId} resume=${creationOpts?.resume ?? "none"} apiType=${resolvedProvider?.apiType ?? "native"} baseUrl=${resolvedProvider?.baseUrl ?? "native"}`);
         const options = {
             systemPrompt,
             settingSources: ["user", "project", "local"],
@@ -4937,27 +5163,23 @@ export class ClaudeAcpAgent {
             // `enableFileCheckpointing` still wins.
             enableFileCheckpointing: true,
             ...userProvidedOptions,
-            // CLAUDE_MODEL_CONFIG env var is a fallback for model
-            // configuration (e.g. Bedrock model ID overrides). When the caller
-            // provides settings via _meta, we intentionally ignore the env var —
-            // the caller is assumed to have full control over model configuration.
-            ...(!userProvidedOptions?.settings &&
-                modelConfig && {
-                settings: {
-                    ...(modelConfig.modelOverrides && { modelOverrides: modelConfig.modelOverrides }),
-                    ...(modelConfig.availableModels && { availableModels: modelConfig.availableModels }),
-                },
-            }),
+            ...(settings && { settings }),
             env,
             // Override certain fields that must be controlled by ACP
             cwd: params.cwd,
             includePartialMessages: true,
             forwardSubagentText,
-            mcpServers: { ...(userProvidedOptions?.mcpServers || {}), ...mcpServers },
+            mcpServers: {
+                ...(userProvidedOptions?.mcpServers || {}),
+                ...mcpServers,
+                ...(fileChangeAuditSupport
+                    ? { [FILE_CHANGE_AUDIT_SERVER_NAME]: fileChangeAuditSupport.mcpServer }
+                    : {}),
+            },
             // If we want bypassPermissions to be an option, we have to allow it here.
             // But it doesn't work in root mode, so we only activate it if it will work.
             allowDangerouslySkipPermissions: ALLOW_BYPASS,
-            permissionMode,
+            permissionMode: initialPermissionMode,
             canUseTool: this.canUseTool(sessionId),
             // Forward MCP elicitation requests onto ACP elicitation. Only attached
             // when the client advertised support, so non-supporting clients keep the
@@ -4987,40 +5209,42 @@ export class ClaudeAcpAgent {
             tools,
             hooks: {
                 ...userProvidedOptions?.hooks,
+                ...(fileChangeAuditSupport
+                    ? {
+                        PreToolUse: [
+                            ...(userProvidedOptions?.hooks?.PreToolUse || []),
+                            { hooks: [fileChangeAuditSupport.preToolUseHook] },
+                        ],
+                    }
+                    : {}),
                 PostToolUse: [
                     ...(userProvidedOptions?.hooks?.PostToolUse || []),
                     {
                         hooks: [
                             createPostToolUseHook({
                                 onEnterPlanMode: async () => {
-                                    await this.client.sessionUpdate({
-                                        sessionId,
-                                        update: {
-                                            sessionUpdate: "current_mode_update",
-                                            currentModeId: "plan",
-                                        },
-                                    });
+                                    await this.sessionModes.publishCurrent(sessionId, "plan");
                                     await this.updateConfigOption(sessionId, MODE_CONFIG_ID, "plan");
                                 },
                             }),
                         ],
                     },
                 ],
+                ...(fileChangeAuditSupport
+                    ? {
+                        Stop: [
+                            ...(userProvidedOptions?.hooks?.Stop || []),
+                            { hooks: [fileChangeAuditSupport.stopHook] },
+                        ],
+                    }
+                    : {}),
                 TaskCreated: [
                     ...(userProvidedOptions?.hooks?.TaskCreated || []),
                     {
                         hooks: [
                             createTaskHook({
                                 taskState,
-                                onChange: async () => {
-                                    await this.client.sessionUpdate({
-                                        sessionId,
-                                        update: {
-                                            sessionUpdate: "plan",
-                                            entries: taskStateToPlanEntries(taskState),
-                                        },
-                                    });
-                                },
+                                onChange: () => this.publishTaskPlan(sessionId, taskState),
                             }),
                         ],
                     },
@@ -5031,35 +5255,24 @@ export class ClaudeAcpAgent {
                         hooks: [
                             createTaskHook({
                                 taskState,
-                                onChange: async () => {
-                                    await this.client.sessionUpdate({
-                                        sessionId,
-                                        update: {
-                                            sessionUpdate: "plan",
-                                            entries: taskStateToPlanEntries(taskState),
-                                        },
-                                    });
-                                },
+                                onChange: () => this.publishTaskPlan(sessionId, taskState),
                             }),
                         ],
                     },
                 ],
             },
-            ...creationOpts,
+            ...(creationOpts.resume !== undefined && { resume: creationOpts.resume }),
+            ...(creationOpts.forkSession !== undefined && { forkSession: creationOpts.forkSession }),
             abortController,
         };
         // Prefer the official ACP `additionalDirectories` field. Fall back to the
         // legacy `_meta.additionalRoots` extension for clients that haven't been
         // updated yet. Either source is merged with directories supplied via
         // `_meta.claudeCode.options.additionalDirectories` (SDK pass-through).
-        const acpAdditionalDirectories = params.additionalDirectories ?? sessionMeta?.additionalRoots ?? [];
-        options.additionalDirectories = [
-            ...(userProvidedOptions?.additionalDirectories ?? []),
-            ...acpAdditionalDirectories,
-        ];
+        options.additionalDirectories = additionalDirectories;
         if (creationOpts?.resume === undefined || creationOpts?.forkSession) {
             // Set our own session id if not resuming an existing session.
-            options.sessionId = sessionId;
+            options.sessionId = creationOpts.publicSessionId ? randomUUID() : sessionId;
         }
         // Handle abort controller from meta options
         if (abortController?.signal.aborted) {
@@ -5114,8 +5327,8 @@ export class ClaudeAcpAgent {
             ? applyAvailableModelsAllowlist(initializationResult.models, settingsAvailableModels, settingsModelOverrides, this.logger)
             : hideDeprecatedModels(initializationResult.models, this.logger);
         const { modelState: models, resumedContextWindow } = await getAvailableModels(q, catalogModels, allowedModels, initializationResult.models, settingsManager, this.logger, creationOpts.resume !== undefined);
-        // Gate `auto` (and future model-specific modes) on the resolved model's
-        // `ModelInfo`. See `buildAvailableModes` for the canonical SDK signal.
+        // Resolve the current model's capabilities separately from the stable
+        // permission-mode catalog advertised to ACP clients.
         // Looked up in the UNfiltered catalog: a session honoring a persisted
         // deprecated preference must keep that model's real capabilities (R4.3).
         // A resumed session can also be running a model outside the
@@ -5156,38 +5369,12 @@ export class ClaudeAcpAgent {
                 },
             ]
             : catalogModels;
-        const availableModes = buildAvailableModes(currentModelInfo);
-        // Clamp `permissionMode` if the resolved session does not offer it. The
-        // common case is `permissions.defaultMode: "auto"` resolving to a model
-        // that does not support auto mode (e.g. Haiku); without this clamp the
-        // SDK would later throw `"auto mode unavailable for this model"` from
-        // `setPermissionMode`. Keep `permissionMode` as the resolved user intent
-        // (matches what was passed into `options.permissionMode` above) and use
-        // `effectiveMode` for the post-clamp value the session actually runs in.
-        let effectiveMode = permissionMode;
-        if (!availableModes.some((m) => m.id === effectiveMode)) {
-            if (effectiveMode === "auto") {
-                this.logger.error(`permissions.defaultMode "auto" is not available for model ` +
-                    `"${models.currentModelId}"; falling back to "default".`);
-            }
-            else {
-                this.logger.error(`permissions.defaultMode "${effectiveMode}" is not available in ` +
-                    `this session; falling back to "default".`);
-            }
-            effectiveMode = "default";
-            // Sync the SDK so it doesn't keep "auto" cached internally. Wrapped in
-            // try/catch since failing here would abort session creation entirely.
-            try {
-                await q.setPermissionMode("default");
-            }
-            catch (err) {
-                this.logger.error("Failed to sync clamped permissionMode to SDK:", err);
-            }
-        }
-        const modes = {
-            currentModeId: effectiveMode,
-            availableModes,
-        };
+        const { modes, autoModeFallbackWarningPending } = await this.sessionModes.initialize({
+            query: q,
+            requestedMode: initialPermissionMode,
+            currentModelInfo,
+            currentModelId: models.currentModelId,
+        });
         const agents = await discoverCustomAgents(q);
         // Only adopt the requested agent as the selected value if it's one we
         // actually surface in the picker. A built-in (filtered out above) or
@@ -5214,6 +5401,7 @@ export class ClaudeAcpAgent {
         const fastMode = {
             supported: currentModelInfo?.supportsFastMode ?? false,
             enabled: fastModeEnabled,
+            useBooleanOption: clientSupportsBooleanConfigOptions(this.clientCapabilities),
             disabledReason: fastModeDisabledReason,
         };
         const configOptions = buildConfigOptions(modes, models, 
@@ -5279,7 +5467,9 @@ export class ClaudeAcpAgent {
             // can rebuild an equivalent query without re-running this assembly.
             queryOptions: options,
             sessionFingerprint: computeSessionFingerprint(params),
+            creationParams: params,
             settingsManager,
+            titles: new SessionTitles(this, sessionId),
             accumulatedUsage: {
                 inputTokens: 0,
                 outputTokens: 0,
@@ -5293,6 +5483,8 @@ export class ClaudeAcpAgent {
             // capability lookups and `resolveModelPreference` (refusal fallback),
             // which must keep seeing deprecated rows (R4.3, visibility-only filter).
             modelInfos,
+            autoModeFallbackWarningShown: false,
+            autoModeFallbackWarningPending,
             configOptions,
             agents,
             currentAgent,
@@ -5311,6 +5503,9 @@ export class ClaudeAcpAgent {
             emittedAssistantText: false,
             owedTrailingIdles: 0,
             messageIdToUuid: new Map(),
+            sessionFailureState: createSessionFailureState(),
+            fileChangeReportRequestIds: new Set(),
+            fileChangeAuditSupport,
         };
         return {
             sessionId,
@@ -5318,6 +5513,41 @@ export class ClaudeAcpAgent {
             configOptions,
         };
     }
+    /**
+     * Provider routing is baked into the environment of each SDK Query. Wait for
+     * all submitted turns to settle, close every query, then resume each Claude
+     * session with the same ID so subsequent turns inherit the new environment.
+     */
+    async enqueueProviderUpdate(config) {
+        const previous = this.providerUpdate?.catch(() => undefined) ?? Promise.resolve();
+        const update = previous.then(async () => {
+            const sessions = Object.entries(this.sessions);
+            const activeTurns = sessions.flatMap(([, session]) => (session.turnQueue ?? []).flatMap((turn) => (turn.completion ? [turn.completion] : [])));
+            if (activeTurns.length > 0) {
+                this.logger.log(`Waiting for ${activeTurns.length} active Claude turn(s) before provider update`);
+                await Promise.all(activeTurns);
+            }
+            this.providerConfig = config;
+            for (const [sessionId, session] of sessions) {
+                if (this.sessions[sessionId] !== session || !session.creationParams) {
+                    continue;
+                }
+                this.logger.log(`Recreating Claude session ${sessionId} for provider update`);
+                this.closeQueryStream(session);
+                delete this.sessions[sessionId];
+                await this.createSession(session.creationParams, { resume: sessionId });
+            }
+        });
+        this.providerUpdate = update;
+        try {
+            await update;
+        }
+        finally {
+            if (this.providerUpdate === update) {
+                this.providerUpdate = null;
+            }
+        }
+    }
 }
 function shouldEmitRawMessage(config, message) {
     if (config === true)
@@ -5405,13 +5635,27 @@ function createEnvForProvider(config) {
     if (!config) {
         return {};
     }
+    const resetRouting = {
+        ANTHROPIC_BASE_URL: "",
+        ANTHROPIC_BEDROCK_BASE_URL: "",
+        ANTHROPIC_VERTEX_BASE_URL: "",
+        CLAUDE_CODE_USE_BEDROCK: "0",
+        CLAUDE_CODE_USE_VERTEX: "0",
+        ANTHROPIC_VERTEX_PROJECT_ID: "",
+        CLOUD_ML_REGION: "",
+        AWS_REGION: "",
+        ANTHROPIC_API_KEY: "",
+        ANTHROPIC_AUTH_TOKEN: "",
+        CLAUDE_CODE_OAUTH_TOKEN: "",
+    };
     const customHeaders = Object.entries(config.headers)
         .map(([key, value]) => `${key}: ${value}`)
         .join("\n");
     if (config.apiType === "bedrock") {
         return {
+            ...resetRouting,
             CLAUDE_CODE_USE_BEDROCK: "1",
-            AWS_BEARER_TOKEN_BEDROCK: " ", // Must be non-empty to bypass pass configuration check
+            AWS_BEARER_TOKEN_BEDROCK: "acp-proxy", // Bypass local AWS credential checks
             ANTHROPIC_BEDROCK_BASE_URL: config.baseUrl,
             ANTHROPIC_CUSTOM_HEADERS: customHeaders,
         };
@@ -5420,6 +5664,7 @@ function createEnvForProvider(config) {
         // `config.vertex` is guaranteed present for vertex by `unstable_setProvider`
         // validation; fall back to empty strings defensively.
         return {
+            ...resetRouting,
             CLAUDE_CODE_USE_VERTEX: "1",
             ANTHROPIC_VERTEX_BASE_URL: config.baseUrl,
             ANTHROPIC_VERTEX_PROJECT_ID: config.vertex?.projectId ?? "",
@@ -5428,9 +5673,10 @@ function createEnvForProvider(config) {
         };
     }
     return {
+        ...resetRouting,
         ANTHROPIC_BASE_URL: config.baseUrl,
         ANTHROPIC_CUSTOM_HEADERS: customHeaders,
-        ANTHROPIC_AUTH_TOKEN: " ", // Must be specified to bypass claude login requirement
+        ANTHROPIC_AUTH_TOKEN: "acp-proxy", // Bypass local Claude login checks
     };
 }
 /**
@@ -5449,50 +5695,6 @@ function isValidBaseUrl(baseUrl) {
     }
     return parsed.protocol === "http:" || parsed.protocol === "https:";
 }
-/**
- * Build the list of permission modes the agent will advertise for the given
- * model. `auto` is gated by `ModelInfo.supportsAutoMode === true`, which is
- * the SDK's model-level availability signal. `undefined`/`false` both exclude
- * `auto`. `bypassPermissions` is still gated by `ALLOW_BYPASS`.
- */
-function buildAvailableModes(modelInfo) {
-    const modes = [];
-    // Only advertise "auto" when the SDK reports the model supports it.
-    if (modelInfo?.supportsAutoMode === true) {
-        modes.push({
-            id: "auto",
-            name: "Auto",
-            description: "Use a model classifier to approve/deny permission prompts",
-        });
-    }
-    modes.push({
-        // Claude Code 2.1.200 renamed this mode to "Manual" across its surfaces;
-        // the wire id stays "default" ("manual" is only an accepted input alias).
-        id: "default",
-        name: "Manual",
-        description: "Standard behavior, prompts for dangerous operations",
-    }, {
-        id: "acceptEdits",
-        name: "Accept Edits",
-        description: "Auto-accept file edit operations",
-    }, {
-        id: "plan",
-        name: "Plan Mode",
-        description: "Planning mode, no actual tool execution",
-    }, {
-        id: "dontAsk",
-        name: "Don't Ask",
-        description: "Don't prompt for permissions, deny if not pre-approved",
-    });
-    if (ALLOW_BYPASS) {
-        modes.push({
-            id: "bypassPermissions",
-            name: "Bypass Permissions",
-            description: "Bypass all permission checks",
-        });
-    }
-    return modes;
-}
 // Translate a UI effort value into the flag-layer payload. The SDK
 // shallow-merges `applyFlagSettings`, drops `undefined` during JSON transport,
 // and only clears a key when an explicit `null` is sent — see
@@ -5523,7 +5725,6 @@ export const BUILTIN_AGENT_NAMES = new Set([
 // reserved sentinel: a custom agent named exactly this would collide with it
 // (two options sharing the value, selection silently routing to `null`), so we
 // exclude that name from discovery.
-export const DEFAULT_AGENT_ID = "default";
 /** Discover user/plugin/project-configured main-thread agents, excluding the
  *  built-in subagents and the reserved "default" sentinel. Returns an empty
  *  list if discovery fails so a flaky control request never blocks session
@@ -5541,13 +5742,12 @@ export async function discoverCustomAgents(q) {
  *  Centralized so the option declarations in `buildConfigOptions` and the
  *  handlers in `setSessionConfigOption`/`applyConfigOptionValue` reference the
  *  same identifiers and can't drift apart. */
-export const MODE_CONFIG_ID = "mode";
+export { MODE_CONFIG_ID };
 export const MODEL_CONFIG_ID = "model";
-export const EFFORT_CONFIG_ID = "effort";
 export const AGENT_CONFIG_ID = "agent";
 export const FAST_MODE_CONFIG_ID = "fast";
-/** Select values for the Fast mode on/off option
- *  (see {@link createFastModeConfigOption}). */
+/** Select-fallback values used when the client has not opted into boolean
+ *  config options (see {@link createFastModeConfigOption}). */
 export const FAST_MODE_ON = "on";
 export const FAST_MODE_OFF = "off";
 const FAST_MODE_DESCRIPTION = "Faster responses on supported models";
@@ -5584,33 +5784,38 @@ const FAST_MODE_UNAVAILABLE_EXPLANATIONS = {
 export function normalizeFastModeDisabledReason(reason) {
     return reason && FAST_MODE_UNAVAILABLE_EXPLANATIONS[reason] ? reason : undefined;
 }
-/** Build the Fast mode config option as a two-value on/off `select`. Emitted
- *  for EVERY Client — the boolean option shape is gone (story 006, R2.1;
- *  retained through the v0.64.0 sync by story 008 R3.4). Only the emitted SHAPE
- *  is fixed to a select; boolean VALUES are still honored on set (see
- *  {@link resolveFastModeEnabled}). This factory is the single source of the
- *  option's shape, re-rendered by `refreshFastModeOption` / `syncFastModeState`
- *  so the shape can never desync.
- *
- *  `disabledReason` (the SDK's `fast_mode_disabled_reason`, upstream v0.64.0) is
- *  folded into the description while the toggle reads off, so a user whose
- *  account or provider can't serve Fast mode sees why instead of a switch that
- *  silently refuses to stay on. Ignored while enabled: a reason reported
- *  alongside an `on`/`cooldown` state isn't blocking anything right now.
+/** Whether the Client advertised support for boolean session config options
+ *  (`session.configOptions.boolean`). Agents MUST only send `type: "boolean"`
+ *  config options to Clients that opt in; otherwise we fall back to a `select`.
+ *  See https://agentclientprotocol.com/rfds/boolean-config-option. */
+export function clientSupportsBooleanConfigOptions(clientCapabilities) {
+    return clientCapabilities?.session?.configOptions?.boolean != null;
+}
+/** Build the Fast mode config option. When the Client supports boolean config
+ *  options we expose a native `type: "boolean"` toggle; otherwise we degrade to
+ *  a two-value `select` ("on"/"off") so older Clients still get a usable
+ *  control.
  *
- *  Upstream's second parameter (`useBooleanOption`) is deliberately absent: the
- *  shape is unconditionally a select, so there is no branch to select. What
- *  guards that is behavioural, not structural — `tests/fast-mode-select-only.
- *  test.ts` proves no argument combination can yield the boolean shape. */
-export function createFastModeConfigOption(enabled, disabledReason) {
+ *  `disabledReason` (the SDK's `fast_mode_disabled_reason`) is folded into the
+ *  description while the toggle reads off, so a user whose account or provider
+ *  can't serve Fast mode sees why instead of a switch that silently refuses to
+ *  stay on. Ignored while enabled: a reason reported alongside an `on`/`cooldown`
+ *  state isn't blocking anything right now. */
+export function createFastModeConfigOption(enabled, useBooleanOption, disabledReason) {
     const explanation = enabled
         ? undefined
         : disabledReason && FAST_MODE_UNAVAILABLE_EXPLANATIONS[disabledReason];
-    return {
+    const base = {
         id: FAST_MODE_CONFIG_ID,
         name: "Fast mode",
         description: explanation ? `${FAST_MODE_DESCRIPTION} — ${explanation}` : FAST_MODE_DESCRIPTION,
         category: "model_config",
+    };
+    if (useBooleanOption) {
+        return { ...base, type: "boolean", currentValue: enabled };
+    }
+    return {
+        ...base,
         type: "select",
         currentValue: enabled ? FAST_MODE_ON : FAST_MODE_OFF,
         options: [
@@ -5620,8 +5825,8 @@ export function createFastModeConfigOption(enabled, disabledReason) {
     };
 }
 /** Resolve the requested Fast mode value from a `session/set_config_option`
- *  request. Accepts the select's "on"/"off" strings or a native boolean,
- *  kept for backward compatibility (R2.3). */
+ *  request. Accepts a native boolean (boolean-capable Clients) or the
+ *  "on"/"off" select-fallback strings. */
 export function resolveFastModeEnabled(params) {
     const value = params.value;
     if (typeof value === "boolean") {
@@ -5643,19 +5848,7 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
  *  callers/tests) omits the row. */
 thinkingEnabled) {
     const options = [
-        {
-            id: MODE_CONFIG_ID,
-            name: "Mode",
-            description: "Session permission mode",
-            category: "mode",
-            type: "select",
-            currentValue: modes.currentModeId,
-            options: modes.availableModes.map((m) => ({
-                value: m.id,
-                name: m.name,
-                description: m.description,
-            })),
-        },
+        SessionModeManager.configOption(modes),
         {
             id: MODEL_CONFIG_ID,
             name: "Model",
@@ -5663,11 +5856,21 @@ thinkingEnabled) {
             category: "model",
             type: "select",
             currentValue: models.currentModelId,
-            options: models.availableModels.map((m) => ({
-                value: m.modelId,
-                name: m.name,
-                description: m.description ?? undefined,
-            })),
+            options: models.availableModels.map((m) => {
+                if (m.modelId === "default") {
+                    const defaultInfo = modelInfos.find((mi) => mi.value === "default");
+                    const resolvedModel = defaultInfo?.resolvedModel;
+                    if (resolvedModel) {
+                        const namedMatch = modelInfos.find((mi) => mi.value !== "default" && mi.resolvedModel === resolvedModel);
+                        return {
+                            value: m.modelId,
+                            name: m.name,
+                            description: namedMatch?.displayName ?? resolvedModel,
+                        };
+                    }
+                }
+                return { value: m.modelId, name: m.name, description: m.description ?? undefined };
+            }),
         },
     ];
     // Add effort level option based on the currently selected model
@@ -5699,10 +5902,10 @@ thinkingEnabled) {
         });
     }
     // Surface the Fast mode toggle only when the current model supports it. The
-    // option is always emitted as a two-value on/off select for every Client
-    // (R2.1); boolean values remain accepted on set for boolean-era clients.
+    // option renders as a native boolean toggle for Clients that opted in, and a
+    // two-value select otherwise.
     if (fastMode?.supported) {
-        options.push(createFastModeConfigOption(fastMode.enabled, fastMode.disabledReason));
+        options.push(createFastModeConfigOption(fastMode.enabled, fastMode.useBooleanOption, fastMode.disabledReason));
     }
     // Surface the Thinking toggle whenever the caller supplies its display
     // state. Unlike Fast mode it is model-independent — no `supported` gate —
@@ -6166,7 +6369,11 @@ pickerModels, sdkModels, settingsManager, logger, isResumedSession) {
         resumedContextWindow,
     };
 }
-function getAvailableSlashCommands(commands) {
+function getAvailableSlashCommands(commands, 
+// Names the CLI tagged terminal-bound on `system`/init (their UX lives in
+// the CLI's own terminal, which ACP clients aren't) — filtered alongside
+// the static list. Raw CLI names, matched before the MCP rename.
+terminalCommands) {
     const UNSUPPORTED_COMMANDS = [
         "clear",
         "cost",
@@ -6178,6 +6385,7 @@ function getAvailableSlashCommands(commands) {
         "todos",
     ];
     const advertised = commands
+        .filter((command) => !terminalCommands?.includes(command.name))
         .map((command) => {
         const input = command.argumentHint
             ? {
@@ -6361,13 +6569,13 @@ function isTaskTool(toolName) {
  *  permission-surfaced tool_call for them (see `ensureToolCallEmitted`) must be
  *  resolved explicitly at tool_result time. */
 function shouldEmitToolCall(toolName) {
-    return toolName !== "TodoWrite" && !isTaskTool(toolName);
+    return toolName !== "TodoWrite" && !isTaskTool(toolName) && !isFileChangeAuditTool(toolName);
 }
 /** Build the Claude Code-specific metadata for a tool call. Bash descriptions
  *  are kept out of ACP's standard `title`, which clients may use as the shell
  *  command preview, while still giving clients access to Claude's concise
  *  human-readable title. */
-function claudeCodeMetaFromToolUse(toolUse) {
+function claudeCodeMetaFromToolUse(toolUse, cwd) {
     const description = toolUse.name === "Bash" &&
         toolUse.input !== null &&
         typeof toolUse.input === "object" &&
@@ -6375,11 +6583,53 @@ function claudeCodeMetaFromToolUse(toolUse) {
         typeof toolUse.input.description === "string"
         ? toolUse.input.description
         : undefined;
+    const skillName = toolUse.name === "Skill"
+        ? toolUse.input?.skill
+        : undefined;
+    const skillPath = skillName ? resolveSkillPath(skillName, cwd) : undefined;
     return {
         toolName: toolUse.name,
         ...(description ? { title: description } : {}),
         ...((toolUse.name === "Agent" || toolUse.name === "Task") && { subagent: true }),
+        ...(skillName ? { skill: skillName } : {}),
+        ...(skillPath ? { skillPath } : {}),
+    };
+}
+/** Roots a skill's directory may sit under, relative to the directory the scope resolves to. */
+const SKILL_CONTAINER_DIRS = [".claude/skills", ".agents/skills"];
+/**
+ * Absolute path of a skill's `SKILL.md`, or `undefined` when none of the known layouts holds one.
+ *
+ * The `Skill` tool reports only the skill's name, so the file has to be located by probing the layouts skills
+ * actually use: project- and user-level `.claude/skills` (plus this repo's `.agents/skills` source of truth), and
+ * for a `<prefix>:<name>` spelling either a plugin (`.claude/plugins/<prefix>/skills/<name>`) or a
+ * directory-scoped skill (`<prefix>/.claude/skills/<name>`), which share that spelling. Only a path that exists
+ * on disk is returned, so a wrong guess costs nothing and clients never render a link to a missing file.
+ */
+function resolveSkillPath(skillName, cwd) {
+    if (!cwd) {
+        return undefined;
+    }
+    const colon = skillName.indexOf(":");
+    const scope = colon < 0 ? undefined : skillName.slice(0, colon);
+    const name = colon < 0 ? skillName : skillName.slice(colon + 1);
+    if (!name) {
+        return undefined;
+    }
+    const candidates = [];
+    const addCandidates = (base) => {
+        for (const container of SKILL_CONTAINER_DIRS) {
+            candidates.push(path.join(base, container, name, "SKILL.md"));
+        }
     };
+    if (scope) {
+        // A `<prefix>:<name>` skill is either directory-scoped or a plugin's; both spellings look identical.
+        addCandidates(path.join(cwd, scope));
+        candidates.push(path.join(cwd, ".claude/plugins", scope, "skills", name, "SKILL.md"));
+    }
+    addCandidates(cwd);
+    addCandidates(os.homedir());
+    return candidates.find((candidate) => existsSync(candidate));
 }
 /** Build the `tool_call` (or, with `refine`, the `tool_call_update`)
  *  notification for a tool_use. Shared by every site that surfaces a tool call:
@@ -6391,7 +6641,7 @@ function claudeCodeMetaFromToolUse(toolUse) {
 function toolCallNotification(toolUse, rawInput, supportsTerminalOutput, cwd, refine = false) {
     if (refine) {
         return {
-            _meta: { claudeCode: claudeCodeMetaFromToolUse(toolUse) },
+            _meta: { claudeCode: claudeCodeMetaFromToolUse(toolUse, cwd) },
             toolCallId: toolUse.id,
             sessionUpdate: "tool_call_update",
             rawInput,
@@ -6400,7 +6650,7 @@ function toolCallNotification(toolUse, rawInput, supportsTerminalOutput, cwd, re
     }
     return {
         _meta: {
-            claudeCode: claudeCodeMetaFromToolUse(toolUse),
+            claudeCode: claudeCodeMetaFromToolUse(toolUse, cwd),
             ...(toolUse.name === "Bash" && supportsTerminalOutput
                 ? { terminal_info: { terminal_id: toolUse.id } }
                 : {}),
@@ -6426,7 +6676,7 @@ function streamedInputRefinement(toolUse, input, supportsTerminalOutput, cwd) {
     const { title, kind, locations } = toolInfoFromToolUse({ ...toolUse, input }, supportsTerminalOutput, cwd);
     return {
         _meta: {
-            claudeCode: claudeCodeMetaFromToolUse({ ...toolUse, input }),
+            claudeCode: claudeCodeMetaFromToolUse({ ...toolUse, input }, cwd),
         },
         toolCallId: toolUse.id,
         sessionUpdate: "tool_call_update",
@@ -6436,33 +6686,6 @@ function streamedInputRefinement(toolUse, input, supportsTerminalOutput, cwd) {
         ...(locations ? { locations } : {}),
     };
 }
-/** Validates the SDK user message's `tool_result_meta` sidecar (emitted on the
- *  wire by CLI ≥ 2.1.216 but absent from sdk.d.ts, hence unknown-typed) into a
- *  by-tool_use_id lookup. Each entry explains why an is_error tool_result
- *  carries harness prose instead of the tool's own output — "user-rejected",
- *  "permission-rule", "interrupted", "cancelled", … (open set: new kinds ship
- *  on the wire ahead of schema updates, so no enum check). Malformed entries
- *  are skipped rather than failing the message. */
-function parseToolResultMeta(raw) {
-    if (!Array.isArray(raw)) {
-        return undefined;
-    }
-    let byToolUseId;
-    for (const entry of raw) {
-        if (typeof entry !== "object" || entry === null) {
-            continue;
-        }
-        const { id, non_execution_kind, user_feedback } = entry;
-        if (typeof id !== "string" || typeof non_execution_kind !== "string") {
-            continue;
-        }
-        (byToolUseId ??= new Map()).set(id, {
-            nonExecutionKind: non_execution_kind,
-            ...(typeof user_feedback === "string" ? { userFeedback: user_feedback } : {}),
-        });
-    }
-    return byToolUseId;
-}
 /**
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
  * Only handles text, image, and thinking chunks for now.
@@ -6472,7 +6695,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
     const registerHooks = options?.registerHooks !== false;
     const supportsTerminalOutput = options?.clientCapabilities?._meta?.["terminal_output"] === true;
     if (typeof content === "string") {
-        if (content.length === 0) {
+        if (content.length === 0 || containsFileChangeAuditMarker(content)) {
             return [];
         }
         const update = {
@@ -6506,6 +6729,13 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
     // Unlike `tool_use_result`, entries carry their own tool_use_id, so batched
     // messages need no single-block guard.
     const toolResultMeta = parseToolResultMeta(options?.toolResultMeta);
+    // A report-phase assistant message may contain a short text preface and the
+    // internal tool call in the same content array. Hide the whole message, not
+    // only the tool block, so it stays absent on session replay as well as live.
+    const containsFileChangeAuditToolUse = content.some((chunk) => (chunk.type === "tool_use" ||
+        chunk.type === "server_tool_use" ||
+        chunk.type === "mcp_tool_use") &&
+        isFileChangeAuditTool(chunk.name));
     const output = [];
     // Only handle the first chunk for streaming; extend as needed for batching
     for (const chunk of content) {
@@ -6513,7 +6743,9 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
         switch (chunk.type) {
             case "text":
             case "text_delta": {
-                if (chunk.text) {
+                if (chunk.text &&
+                    !containsFileChangeAuditToolUse &&
+                    !containsFileChangeAuditMarker(chunk.text)) {
                     update = {
                         sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
                         content: {
@@ -6525,21 +6757,22 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 break;
             }
             case "image":
-                update = {
-                    sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
-                    content: {
-                        type: "image",
-                        data: chunk.source.type === "base64" ? chunk.source.data : "",
-                        mimeType: chunk.source.type === "base64" ? chunk.source.media_type : "",
-                        uri: chunk.source.type === "url" ? chunk.source.url : undefined,
-                    },
-                };
+                if (!containsFileChangeAuditToolUse)
+                    update = {
+                        sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
+                        content: {
+                            type: "image",
+                            data: chunk.source.type === "base64" ? chunk.source.data : "",
+                            mimeType: chunk.source.type === "base64" ? chunk.source.media_type : "",
+                            uri: chunk.source.type === "url" ? chunk.source.url : undefined,
+                        },
+                    };
                 break;
             case "thinking":
             case "thinking_delta": {
                 // Recent models default `thinking.display` to "omitted", which streams
                 // signature-only thinking blocks whose text is empty.
-                if (chunk.thinking) {
+                if (chunk.thinking && !containsFileChangeAuditToolUse) {
                     update = {
                         sessionUpdate: "agent_thought_chunk",
                         content: {
@@ -6555,7 +6788,11 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             case "mcp_tool_use": {
                 const alreadyCached = chunk.id in toolUseCache;
                 toolUseCache[chunk.id] = chunk;
-                if (chunk.name === "TodoWrite") {
+                if (isFileChangeAuditTool(chunk.name)) {
+                    // Wrapper-owned audit protocol: never surface or register generic
+                    // PostToolUse callbacks for the internal tool.
+                }
+                else if (chunk.name === "TodoWrite") {
                     // @ts-expect-error - sometimes input is empty object or undefined
                     if (Array.isArray(chunk.input?.todos)) {
                         update = {
@@ -6679,6 +6916,10 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     logger.error(`[claude-agent-acp] Got a tool result for tool use that wasn't tracked: ${chunk.tool_use_id}`);
                     break;
                 }
+                if (isFileChangeAuditTool(toolUse.name)) {
+                    delete toolUseCache[chunk.tool_use_id];
+                    break;
+                }
                 // A permission request may have surfaced a plan-rendered (TodoWrite) or
                 // suppressed (Task*) tool as a real tool_call so the request referenced
                 // a tool call the client knows about (see `ensureToolCallEmitted`,
@@ -6709,20 +6950,40 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 }
                 if (isTaskTool(toolUse.name)) {
                     // Headless/SDK sessions emit Task* tools instead of TodoWrite.
-                    // TaskCreate / TaskUpdate mutate the accumulated task list; TaskList
-                    // and TaskGet are read-only so we just suppress their tool_call /
-                    // tool_result events. The plan update is emitted as a snapshot of
-                    // the accumulated state, mirroring the legacy TodoWrite behavior.
+                    // TaskCreate / TaskUpdate mutate the accumulated task list. TaskList
+                    // reconciles it from the SDK's authoritative snapshot, which repairs
+                    // resumed or compacted sessions whose creating calls are no longer in
+                    // replay history. TaskGet is read-only and remains suppressed. Plan
+                    // updates always carry the full accumulated snapshot, mirroring the
+                    // legacy TodoWrite behavior.
                     const isError = "is_error" in chunk && chunk.is_error;
+                    let shouldEmitTaskPlan = false;
                     if (!isError) {
                         if (toolUse.name === "TaskCreate") {
-                            applyTaskCreate(taskState, toolUse.input, parseTaskCreateOutput(chunk.content));
+                            applyTaskCreate(taskState, toolUse.input, parseTaskCreateOutput(toolUseResult) ?? parseTaskCreateOutput(chunk.content));
+                            shouldEmitTaskPlan = true;
                         }
                         else if (toolUse.name === "TaskUpdate") {
-                            applyTaskUpdate(taskState, toolUse.input);
+                            const input = toolUse.input;
+                            const output = parseTaskUpdateOutput(toolUseResult, input?.taskId) ??
+                                parseTaskUpdateOutput(chunk.content, input?.taskId);
+                            // Older CLI transcripts have no structured output, so retain the
+                            // input-based fallback. When an output is available, only apply a
+                            // confirmed update for the same task.
+                            if (!output || (output.success && output.taskId === input?.taskId)) {
+                                applyTaskUpdate(taskState, input);
+                                shouldEmitTaskPlan = true;
+                            }
+                        }
+                        else if (toolUse.name === "TaskList") {
+                            const output = parseTaskListOutput(toolUseResult) ?? parseTaskListOutput(chunk.content);
+                            if (output) {
+                                applyTaskList(taskState, output);
+                                shouldEmitTaskPlan = true;
+                            }
                         }
                     }
-                    if (!isError && (toolUse.name === "TaskCreate" || toolUse.name === "TaskUpdate")) {
+                    if (shouldEmitTaskPlan) {
                         update = {
                             sessionUpdate: "plan",
                             entries: taskStateToPlanEntries(taskState),
@@ -6762,7 +7023,12 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                         toolCallId: chunk.tool_use_id,
                         sessionUpdate: "tool_call_update",
                         status: "is_error" in chunk && chunk.is_error ? "failed" : "completed",
-                        rawOutput: chunk.content,
+                        // terminal_output already carried the exact bytes in the preceding
+                        // update. Repeating them as rawOutput wastes bandwidth and lets a
+                        // client accidentally render the same output twice.
+                        ...(toolMeta?.terminal_output
+                            ? {}
+                            : { rawOutput: exitPlanModeRawOutput(toolUse.name, chunk.content) }),
                         ...toolUpdate,
                     };
                 }
@@ -6783,7 +7049,6 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             case "compaction":
             case "compaction_delta":
             case "advisor_tool_result":
-            case "mid_conv_system":
             case "fallback":
                 break;
             default:
@@ -6940,7 +7205,7 @@ export async function runPromptWithCancellation(agent, params, signal) {
         signal.removeEventListener("abort", onAbort);
     }
 }
-export function runAcp() {
+export function runAcp(logger) {
     const input = nodeToWebWritable(process.stdout);
     const output = nodeToWebReadable(process.stdin);
     const stream = ndJsonStream(input, output);
@@ -6973,7 +7238,7 @@ export function runAcp() {
         .onRequest(STEER_METHOD, { parse: parseSteerRequest }, (ctx) => agent.steer(ctx.params))
         .onRequest(GOAL_CONTROL_METHOD, { parse: parseGoalRequest }, (ctx) => agent.goal(ctx.params))
         .connect(stream);
-    agent = new ClaudeAcpAgent(new ClientConnection(connection.client));
+    agent = new ClaudeAcpAgent(new ClientConnection(connection.client), logger);
     return { connection, agent };
 }
 function commonPrefixLength(a, b) {
@@ -7068,6 +7333,7 @@ const PROVIDER_ROUTING_ENV_VARS = [
     "ANTHROPIC_CUSTOM_HEADERS",
     "ANTHROPIC_API_KEY",
     "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
 ];
 /** Stable identifier for the LLM backend a session's query is created against,
  *  used to scope {@link contextWindowCache} per backend. Positional `\0`-join