@agentclientprotocol/claude-agent-acp 0.66.0 → 0.68.0

package/dist/acp-agent.js

@@ -3,6 +3,7 @@ import { deleteSession, getSessionInfo, getSessionMessages, listSessions, query,
 import { GOAL_ACTIONS, GOAL_CONTROL_METHOD, GOAL_EXTENSION_VERSION, goalUpdateFromPrompt, parseGoalRequest, toGoalSnapshot, } from "./goal-extension.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";
@@ -10,11 +11,13 @@ import { promisify } from "node:util";
 import packageJson from "../package.json" with { type: "json" };
 import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createElicitationResponseToElicitResult, extractAskUserQuestions, extractRefusalFallbackPrompt, mcpElicitationToCreateRequest, REFUSAL_FALLBACK_DIALOG_KIND, refusalFallbackResultFromResponse, refusalFallbackToCreateRequest, } from "./elicitation.js";
 import { SettingsManager } from "./settings.js";
-import { applyTaskCreate, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
+import { activeUsageLimitMessage, airSessionFailureCapabilityMeta, assistantMessageText, createSessionFailureState, isSyntheticUsageLimitMessage, providerFailureCategory, SessionFailureController, sessionFailureMeta, supportsAirSessionFailures, } from "./session-failure-extension.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";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
 const execFileAsync = promisify(execFile);
 const MAX_TITLE_LENGTH = 256;
+const MAX_INLINE_FAILURE_TITLE_LENGTH = 256;
 function sanitizeTitle(text) {
     // Replace newlines and collapse whitespace
     const sanitized = text
@@ -100,11 +103,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",
@@ -143,17 +148,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;
@@ -578,9 +575,7 @@ export class ClaudeAcpAgent {
     clientCapabilities;
     logger;
     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;
     /** Grace period before a `session/cancel` forces a wedged prompt loop to
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
@@ -734,6 +729,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(),
                 steering: {
                     supported: true,
                 },
@@ -847,21 +843,13 @@ 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();
         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] };
     }
@@ -903,30 +891,43 @@ export class ClaudeAcpAgent {
         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;
         }
         // 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
@@ -966,6 +967,9 @@ export class ClaudeAcpAgent {
         if (session.queryClosed) {
             throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
         }
+        if (Array.from(session.taskState.values()).some((task) => task.status !== "completed")) {
+            await this.publishTaskPlan(params.sessionId, session.taskState);
+        }
         const userMessage = promptToClaude(params);
         const promptUuid = randomUUID();
         userMessage.uuid = promptUuid;
@@ -1021,6 +1025,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) {
@@ -1168,6 +1181,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.
@@ -1221,11 +1236,50 @@ export class ClaudeAcpAgent {
             }
             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
@@ -1504,6 +1558,7 @@ 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;
             }
             turn.settled = true;
@@ -1517,6 +1572,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),
+            });
+        };
         /** Reject every in-flight turn — used when the stream dies. */
         const failAllTurns = (error) => {
             disarmForceCancel(session);
@@ -1634,6 +1714,24 @@ export class ClaudeAcpAgent {
                 pendingNext = null;
                 const { value: message, done } = raced.result;
                 if (done || !message) {
+                    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
@@ -1785,6 +1883,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
@@ -1977,7 +2092,7 @@ 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
@@ -2035,7 +2150,7 @@ export class ClaudeAcpAgent {
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "available_commands_update",
-                                        availableCommands: getAvailableSlashCommands(message.commands),
+                                        availableCommands: getAvailableSlashCommands(message.commands, session.terminalSlashCommands),
                                     },
                                 });
                                 break;
@@ -2177,9 +2292,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
@@ -2199,10 +2319,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
@@ -2216,26 +2347,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);
                                 }
@@ -2473,6 +2631,7 @@ export class ClaudeAcpAgent {
                             }
                             if (session.cancelled) {
                                 if (!isAutonomousResult) {
+                                    await clearFailuresFromEarlierTurns();
                                     stopReason = "cancelled";
                                 }
                                 break;
@@ -2508,6 +2667,7 @@ export class ClaudeAcpAgent {
                                 }
                                 break;
                             }
+                            await clearFailuresFromEarlierTurns();
                             // 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
@@ -2544,10 +2704,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") {
@@ -2555,7 +2720,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
@@ -2591,17 +2756,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";
@@ -2875,6 +3052,10 @@ export class ClaudeAcpAgent {
                         if (message.type === "assistant" && message.parent_tool_use_id === null) {
                             lastAssistantUsage = snapshotFromUsage(message.message.usage);
                             lastAssistantTotalUsage = totalTokens(lastAssistantUsage);
+                            lastAssistantWasUsageLimit = isSyntheticUsageLimitMessage(message.message);
+                            if (message.error || lastAssistantWasUsageLimit) {
+                                lastAssistantFailureTitle = assistantMessageText(message.message);
+                            }
                             if (message.message.model && message.message.model !== "<synthetic>") {
                                 lastAssistantModel = message.message.model;
                             }
@@ -2933,7 +3114,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;
@@ -3095,13 +3287,22 @@ 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);
+                        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);
@@ -3123,6 +3324,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
@@ -3136,7 +3350,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);
             }
         }
@@ -3584,9 +3800,28 @@ export class ClaudeAcpAgent {
     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;
         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
@@ -3602,6 +3837,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);
@@ -3992,7 +4242,7 @@ export class ClaudeAcpAgent {
             sessionId,
             update: {
                 sessionUpdate: "available_commands_update",
-                availableCommands: getAvailableSlashCommands(commands),
+                availableCommands: getAvailableSlashCommands(commands, session.terminalSlashCommands),
             },
         });
     }
@@ -4506,15 +4756,7 @@ export class ClaudeAcpAgent {
                         hooks: [
                             createTaskHook({
                                 taskState,
-                                onChange: async () => {
-                                    await this.client.sessionUpdate({
-                                        sessionId,
-                                        update: {
-                                            sessionUpdate: "plan",
-                                            entries: taskStateToPlanEntries(taskState),
-                                        },
-                                    });
-                                },
+                                onChange: () => this.publishTaskPlan(sessionId, taskState),
                             }),
                         ],
                     },
@@ -4525,15 +4767,7 @@ export class ClaudeAcpAgent {
                         hooks: [
                             createTaskHook({
                                 taskState,
-                                onChange: async () => {
-                                    await this.client.sessionUpdate({
-                                        sessionId,
-                                        update: {
-                                            sessionUpdate: "plan",
-                                            entries: taskStateToPlanEntries(taskState),
-                                        },
-                                    });
-                                },
+                                onChange: () => this.publishTaskPlan(sessionId, taskState),
                             }),
                         ],
                     },
@@ -4762,6 +4996,7 @@ export class ClaudeAcpAgent {
             emittedAssistantText: false,
             owedTrailingIdles: 0,
             messageIdToUuid: new Map(),
+            sessionFailureState: createSessionFailureState(),
         };
         return {
             sessionId,
@@ -5113,11 +5348,21 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
             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
@@ -5549,7 +5794,11 @@ async function getAvailableModels(query, models, sdkModels, settingsManager, log
         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",
@@ -5561,6 +5810,7 @@ function getAvailableSlashCommands(commands) {
         "todos",
     ];
     return commands
+        .filter((command) => !terminalCommands?.includes(command.name))
         .map((command) => {
         const input = command.argumentHint
             ? {
@@ -5739,7 +5989,7 @@ function shouldEmitToolCall(toolName) {
  *  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" &&
@@ -5747,12 +5997,54 @@ 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:
  *  the streamed tool_use path (first encounter → tool_call, later encounter →
@@ -5763,7 +6055,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,
@@ -5772,7 +6064,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 } }
                 : {}),
@@ -5798,7 +6090,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",
@@ -6081,20 +6373,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),