@agentclientprotocol/claude-agent-acp 0.65.0 → 0.67.0

package/dist/acp-agent.js

@@ -1,7 +1,9 @@
 import { agent as acpAgent, methods, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk";
 import { deleteSession, getSessionInfo, 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 { 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";
@@ -9,7 +11,7 @@ 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 { 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);
@@ -99,11 +101,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",
@@ -154,9 +158,118 @@ const PROVIDER_ID = "main";
  */
 const SUPPORTED_PROTOCOLS = ["anthropic", "bedrock", "vertex"];
 const SUBAGENT_TRANSCRIPT_CAPABILITY = "subagent-transcript";
+// This is a protocol namespace, not user-facing branding: `jetbrains` owns the
+// non-standard contract and `air` identifies the client defining its rendering
+// semantics, without affecting unrelated JetBrains ACP clients.
+const JETBRAINS_META_KEY = "jetbrains";
+const AIR_META_KEY = "air";
+const AIR_EXTENSION_VERSION_KEY = "version";
+const AIR_EXTENSION_CAPABILITIES_KEY = "capabilities";
+const AIR_SESSION_FAILURE_KEY = "sessionFailure";
+const AIR_EXTENSION_VERSION = 1;
 function supportsSubagentTranscript(capabilities) {
     return capabilities?._meta?.[SUBAGENT_TRANSCRIPT_CAPABILITY] === true;
 }
+const AIR_FAILURE_PRESENTATION = {
+    // A non-fatal notice whose wording comes from the adapter or the SDK, so this message is only the
+    // fallback for an advisory published without one.
+    advisory: {
+        message: "Claude reported a notice.",
+        retryable: false,
+        actions: [],
+    },
+    auth_required: {
+        message: "Sign in to continue using Claude.",
+        retryable: false,
+        actions: ["login"],
+    },
+    bad_request: {
+        message: "Claude could not process this request.",
+        retryable: false,
+        actions: ["new_turn"],
+    },
+    budget_exhausted: {
+        message: "This Claude session reached its configured budget.",
+        retryable: false,
+        actions: ["new_session"],
+    },
+    context_exhausted: {
+        message: "This Claude turn reached its configured limit.",
+        retryable: false,
+        actions: ["new_turn"],
+    },
+    internal_error: {
+        message: "Claude Agent encountered an internal error.",
+        retryable: true,
+        actions: ["retry"],
+    },
+    overloaded: {
+        message: "Claude is temporarily overloaded.",
+        retryable: true,
+        actions: ["retry"],
+    },
+    provider_error: {
+        message: "The model provider reported an error.",
+        retryable: true,
+        actions: ["retry"],
+    },
+    quota_exhausted: {
+        message: "The Claude account has no available quota.",
+        retryable: false,
+        actions: ["new_session"],
+    },
+    rate_limited: {
+        message: "Claude is temporarily rate limited.",
+        retryable: true,
+        actions: ["retry"],
+    },
+    transport_lost: {
+        message: "The connection to Claude was lost.",
+        retryable: false,
+        actions: ["new_session"],
+    },
+    worker_shutdown: {
+        message: "The Claude worker is shutting down.",
+        retryable: false,
+        actions: ["new_session"],
+    },
+};
+function supportsAirSessionFailures(capabilities) {
+    const jetbrains = capabilities?._meta?.[JETBRAINS_META_KEY];
+    const air = jetbrains?.[AIR_META_KEY];
+    const version = air?.[AIR_EXTENSION_VERSION_KEY];
+    const advertised = air?.[AIR_EXTENSION_CAPABILITIES_KEY];
+    return (typeof version === "number" &&
+        Number.isFinite(version) &&
+        Number.isInteger(version) &&
+        version >= AIR_EXTENSION_VERSION &&
+        Array.isArray(advertised) &&
+        advertised.some((capability) => capability === AIR_SESSION_FAILURE_KEY));
+}
+function providerFailureCategory(errorKind) {
+    switch (errorKind) {
+        case "authentication_failed":
+        case "oauth_org_not_allowed":
+            return "auth_required";
+        case "billing_error":
+            return "quota_exhausted";
+        case "rate_limit":
+            return "rate_limited";
+        case "overloaded":
+            return "overloaded";
+        case "invalid_request":
+        case "model_not_found":
+            return "bad_request";
+        case "max_output_tokens":
+            return "context_exhausted";
+        case "server_error":
+        case "unknown":
+        case undefined:
+            return "provider_error";
+        default:
+            return "provider_error";
+    }
+}
 function parentToolUseIdOf(message) {
     if (!("parent_tool_use_id" in message))
         return null;
@@ -733,9 +846,20 @@ 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: {
+                [JETBRAINS_META_KEY]: {
+                    [AIR_META_KEY]: {
+                        [AIR_EXTENSION_VERSION_KEY]: AIR_EXTENSION_VERSION,
+                        [AIR_EXTENSION_CAPABILITIES_KEY]: [AIR_SESSION_FAILURE_KEY],
+                    },
+                },
                 steering: {
                     supported: true,
                 },
+                goal: {
+                    version: GOAL_EXTENSION_VERSION,
+                    controlMethod: GOAL_CONTROL_METHOD,
+                    actions: [...GOAL_ACTIONS],
+                },
             },
         };
     }
@@ -960,6 +1084,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;
@@ -986,8 +1113,73 @@ export class ClaudeAcpAgent {
         session.turnQueue.push(turn);
         session.input.push(userMessage);
         this.ensureConsumer(session, params.sessionId);
+        await this.publishGoalFromPrompt(params.sessionId, firstText, promptUuid);
         return response;
     }
+    async goal(params) {
+        const command = params.action === "set" ? `/goal ${params.objective}` : "/goal clear";
+        const prompt = [{ type: "text", text: command }];
+        const steering = await this.steer({
+            sessionId: params.sessionId,
+            prompt,
+            _meta: { steering: { idleBehavior: "promptRequired" } },
+        });
+        if (steering.outcome === "promptRequired") {
+            await this.prompt({ sessionId: params.sessionId, prompt });
+        }
+        return {};
+    }
+    async publishGoal(sessionId, goal) {
+        const session = this.sessions[sessionId];
+        if (session) {
+            session.lastPublishedGoal = goal;
+        }
+        await this.client.sessionUpdate({
+            sessionId,
+            update: {
+                sessionUpdate: "session_info_update",
+                _meta: { goal },
+            },
+        });
+    }
+    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) {
+            const session = this.sessions[sessionId];
+            if (session) {
+                session.pendingGoalUpdate = {
+                    commandUuid,
+                    expected: goalUpdate,
+                    previous: session.lastPublishedGoal,
+                    started: false,
+                };
+            }
+            await this.publishGoal(sessionId, goalUpdate);
+        }
+    }
+    async publishRuntimeGoal(sessionId, goal) {
+        const session = this.sessions[sessionId];
+        const pending = session?.pendingGoalUpdate;
+        if (pending) {
+            const matchesPending = pending.expected === null
+                ? goal === null
+                : goal !== null && goal.objective === pending.expected.objective;
+            if (!matchesPending) {
+                return;
+            }
+            session.pendingGoalUpdate = undefined;
+        }
+        await this.publishGoal(sessionId, goal);
+    }
     /** Steer the session per the ACP steering wire protocol: inject a follow-up
      *  message into the turn that is currently running. If that turn already
      *  settled, the established default starts a new detached turn; Hosts may opt
@@ -1068,6 +1260,8 @@ export class ClaudeAcpAgent {
             turnInFlight.deferredSettle = undefined;
         }
         session.input.push(userMessage);
+        const firstText = params.prompt[0]?.type === "text" ? params.prompt[0].text : "";
+        await this.publishGoalFromPrompt(sessionId, firstText, steeredUuid);
         return { outcome: "injected" };
     }
     /** Lazily start the per-session consumer that drains the SDK query stream for
@@ -1157,6 +1351,115 @@ export class ClaudeAcpAgent {
             }
             await this.client.sessionUpdate(notification);
         };
+        const isAdvisory = (failure) => failure.severity === "warning";
+        const failureRevisions = new Map();
+        const sessionFailureEpoch = randomUUID();
+        const activeSessionFailures = new Map();
+        let pendingWorkerShutdown = false;
+        const isCurrentConsumer = () => this.sessions[params.sessionId] === session;
+        const sessionFailureMeta = (failure, phase) => {
+            const presentation = AIR_FAILURE_PRESENTATION[failure.category];
+            return {
+                [JETBRAINS_META_KEY]: {
+                    [AIR_META_KEY]: {
+                        [AIR_EXTENSION_VERSION_KEY]: AIR_EXTENSION_VERSION,
+                        [AIR_SESSION_FAILURE_KEY]: {
+                            id: failure.id,
+                            revision: failure.revision,
+                            phase,
+                            category: failure.category,
+                            source: "claude",
+                            safeMessage: failure.safeMessage ?? presentation.message,
+                            retryable: presentation.retryable,
+                            actions: presentation.actions,
+                            ...(failure.turnId ? { turnId: failure.turnId } : {}),
+                            ...(failure.severity ? { severity: failure.severity } : {}),
+                        },
+                    },
+                },
+            };
+        };
+        const emitSessionFailure = async (failure, phase) => {
+            if (!isCurrentConsumer()) {
+                this.logger.error(`Session ${params.sessionId}: ignored AIR session failure from a stale query consumer`);
+                return false;
+            }
+            try {
+                await sendUpdate({
+                    sessionId: params.sessionId,
+                    update: {
+                        sessionUpdate: "session_info_update",
+                        _meta: sessionFailureMeta(failure, phase),
+                    },
+                });
+                return true;
+            }
+            catch (error) {
+                this.logger.error(`Session ${params.sessionId}: failed to publish AIR session failure: ${error}`);
+                return false;
+            }
+        };
+        const clearSessionFailure = async (shouldClear = () => true) => {
+            if (!supportsAirSessionFailures(this.clientCapabilities))
+                return;
+            for (const failure of [...activeSessionFailures.values()]) {
+                if (!shouldClear(failure))
+                    continue;
+                const cleared = {
+                    ...failure,
+                    revision: failure.revision + 1,
+                };
+                if (await emitSessionFailure(cleared, "cleared")) {
+                    failureRevisions.set(cleared.id, cleared.revision);
+                    activeSessionFailures.delete(cleared.id);
+                }
+            }
+        };
+        const createSessionFailure = async (category, options = {}) => {
+            if (!supportsAirSessionFailures(this.clientCapabilities) || !isCurrentConsumer()) {
+                return undefined;
+            }
+            // An advisory is not a failure of the turn: it keeps its own id namespace and its own slot, so
+            // it neither clears an actionable error nor is cleared by one. Only the newest advisory
+            // matters, so they all share one id and bump its revision.
+            if (category === "advisory") {
+                const id = `${params.sessionId}:notice:${sessionFailureEpoch}`;
+                return {
+                    id,
+                    revision: (failureRevisions.get(id) ?? 0) + 1,
+                    category,
+                    severity: "warning",
+                    ...(options.safeMessage ? { safeMessage: options.safeMessage } : {}),
+                };
+            }
+            const turnId = options.turnScoped === false ? undefined : session.activeTurn?.promptUuid;
+            const id = turnId
+                ? `${turnId}:error`
+                : `${params.sessionId}:session-error:${sessionFailureEpoch}`;
+            await clearSessionFailure((failure) => failure.id !== id && !isAdvisory(failure));
+            return {
+                id,
+                revision: (failureRevisions.get(id) ?? 0) + 1,
+                category,
+                ...(turnId ? { turnId } : {}),
+            };
+        };
+        const publishSessionFailure = async (category, options = {}) => {
+            const failure = await createSessionFailure(category, options);
+            if (!failure)
+                return;
+            if (await emitSessionFailure(failure, "active")) {
+                failureRevisions.set(failure.id, failure.revision);
+                activeSessionFailures.set(failure.id, failure);
+            }
+        };
+        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 clearSessionFailure((failure) => failure.turnId !== activeTurnId && !isAdvisory(failure));
+        };
+        const internalErrorForClient = (data, rawDetail) => RequestError.internalError(data, supportsAirSessionFailures(this.clientCapabilities) ? undefined : rawDetail);
         const resetTurnScratch = () => {
             lastAssistantTotalUsage = null;
             lastAssistantUsage = null;
@@ -1440,6 +1743,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;
@@ -1453,6 +1757,32 @@ 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 (category, error) => {
+            if (!supportsAirSessionFailures(this.clientCapabilities)) {
+                failActive(error);
+                return;
+            }
+            if (!session.activeTurn || session.activeTurn.settled) {
+                this.logger.error(`Session ${params.sessionId}: cannot attach ${category} to a prompt response because no active turn exists; publishing a session-scoped failure`);
+                await publishSessionFailure(category, { turnScoped: false });
+                return;
+            }
+            const failure = await createSessionFailure(category);
+            if (!failure) {
+                failActive(error);
+                return;
+            }
+            failureRevisions.set(failure.id, failure.revision);
+            activeSessionFailures.set(failure.id, failure);
+            settleActive({
+                stopReason: "end_turn",
+                usage: sessionUsage(session),
+                _meta: sessionFailureMeta(failure, "active"),
+            });
+        };
         /** Reject every in-flight turn — used when the stream dies. */
         const failAllTurns = (error) => {
             disarmForceCancel(session);
@@ -1570,6 +1900,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
@@ -1698,6 +2046,14 @@ export class ClaudeAcpAgent {
                     }
                     continue;
                 }
+                // `active_goal` is emitted by the Claude runtime but is not currently
+                // included in the public SDKMessage union. Handle it before the
+                // exhaustive switch and publish only the provider-neutral ACP shape.
+                if (message.type === "active_goal") {
+                    const activeGoal = message;
+                    await this.publishRuntimeGoal(params.sessionId, toGoalSnapshot(activeGoal));
+                    continue;
+                }
                 switch (message.type) {
                     case "system":
                         switch (message.subtype) {
@@ -1713,6 +2069,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
@@ -1905,7 +2278,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));
                                     }
                                     // The SDK generates the session title in a background task and
                                     // persists it to the session file; `idle` is the turn-over
@@ -1963,7 +2336,7 @@ export class ClaudeAcpAgent {
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "available_commands_update",
-                                        availableCommands: getAvailableSlashCommands(message.commands),
+                                        availableCommands: getAvailableSlashCommands(message.commands, session.terminalSlashCommands),
                                     },
                                 });
                                 break;
@@ -2105,9 +2478,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
@@ -2144,7 +2522,15 @@ 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})`
                                     : "";
@@ -2153,17 +2539,29 @@ export class ClaudeAcpAgent {
                                     : "";
                                 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 fallbackNotice = `${message.original_model} declined this request${category}; ` +
+                                    `retried with ${message.fallback_model}. ${outcome}${explanation}`;
+                                // 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)) {
+                                    await publishSessionFailure("advisory", { safeMessage: fallbackNotice });
+                                }
+                                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);
                                 }
@@ -2268,6 +2666,20 @@ export class ClaudeAcpAgent {
                             if (!isAutonomousResult) {
                                 recordResultForOrphanCommands();
                                 ensureActiveTurn();
+                                // Once the submitted goal command has produced its own result,
+                                // no older runtime update can still precede it in the ordered
+                                // SDK stream. Stop suppressing updates even when this runtime
+                                // omitted the matching active_goal notification entirely.
+                                if (session.pendingGoalUpdate?.started) {
+                                    const pendingGoalUpdate = session.pendingGoalUpdate;
+                                    session.pendingGoalUpdate = undefined;
+                                    const goalCommandFailed = message.is_error ||
+                                        message.stop_reason === "refusal" ||
+                                        ("result" in message && message.result.includes("Please run /login"));
+                                    if (goalCommandFailed) {
+                                        await this.publishGoal(params.sessionId, pendingGoalUpdate.previous ?? null);
+                                    }
+                                }
                             }
                             // A result closes the stretch of output it terminates: snapshot
                             // the delivery record — AFTER ensureActiveTurn, whose held-turn
@@ -2387,6 +2799,7 @@ export class ClaudeAcpAgent {
                             }
                             if (session.cancelled) {
                                 if (!isAutonomousResult) {
+                                    await clearFailuresFromEarlierTurns();
                                     stopReason = "cancelled";
                                 }
                                 break;
@@ -2422,6 +2835,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
@@ -2447,10 +2861,24 @@ export class ClaudeAcpAgent {
                                 settleOrDefer({ stopReason: "refusal", usage: sessionUsage(session) });
                                 break;
                             }
+                            // A priority:'now' steer can make the SDK terminate the
+                            // interrupted cycle with an error-shaped diagnostic result
+                            // before it replays the injected message's echo. That result is
+                            // not the steered command's outcome: keep it on the steer lane
+                            // and let the cycle after the pending echo decide the turn.
+                            if (message.is_error &&
+                                isSteering(session.activeTurn) &&
+                                session.activeTurn.steeredEchoes.size > 0) {
+                                settleOrDefer({ stopReason: "end_turn", usage: sessionUsage(session) });
+                                break;
+                            }
+                            if (!message.is_error) {
+                                await clearSessionFailure();
+                            }
                             switch (message.subtype) {
                                 case "success": {
                                     if (message.result.includes("Please run /login")) {
-                                        failActive(RequestError.authRequired());
+                                        await failActiveWithSessionFailure("auth_required", RequestError.authRequired());
                                         break;
                                     }
                                     if (message.stop_reason === "max_tokens") {
@@ -2458,7 +2886,7 @@ export class ClaudeAcpAgent {
                                         break;
                                     }
                                     if (message.is_error) {
-                                        failActive(RequestError.internalError(errorKindData(lastAssistantError), message.result));
+                                        await failActiveWithSessionFailure(providerFailureCategory(lastAssistantError), internalErrorForClient(errorKindData(lastAssistantError), message.result));
                                         break;
                                     }
                                     // The result text is forwarded in two cases. Local-only
@@ -2494,17 +2922,29 @@ export class ClaudeAcpAgent {
                                         break;
                                     }
                                     if (message.is_error) {
-                                        failActive(RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                        await failActiveWithSessionFailure(providerFailureCategory(lastAssistantError), internalErrorForClient(errorKindData(lastAssistantError), 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));
+                                        break;
+                                    }
+                                    stopReason = "max_turn_requests";
+                                    break;
                                 case "error_max_turns":
+                                    if (message.is_error) {
+                                        await failActiveWithSessionFailure("provider_error", internalErrorForClient(errorKindData(lastAssistantError), 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));
                                         break;
                                     }
                                     stopReason = "max_turn_requests";
@@ -2683,6 +3123,9 @@ export class ClaudeAcpAgent {
                         // is still promoted — activateTurn() clears the flag. The turn's own
                         // echo is then dropped from the feed (the client already shows it).
                         if (message.type === "user" && "uuid" in message && message.uuid) {
+                            if (session.pendingGoalUpdate?.commandUuid === message.uuid) {
+                                session.pendingGoalUpdate.started = true;
+                            }
                             const queued = findUnsettledTurn(message.uuid);
                             if (queued) {
                                 // Only (re)activate if this isn't already the active turn — a
@@ -2833,7 +3276,7 @@ export class ClaudeAcpAgent {
                             break;
                         }
                         if (message.type === "assistant" && isSyntheticLoginMessage(message.message)) {
-                            failActive(RequestError.authRequired());
+                            await failActiveWithSessionFailure("auth_required", RequestError.authRequired());
                             break;
                         }
                         let content;
@@ -2995,13 +3438,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 clearSessionFailure((failure) => failure.category === "auth_required");
+                        }
                         break;
                     default:
                         unreachable(message, this.logger);
@@ -3023,6 +3475,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
@@ -3036,7 +3501,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);
             }
         }
@@ -3078,6 +3545,14 @@ export class ClaudeAcpAgent {
             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.
+        if (isSteering(session.activeTurn)) {
+            for (const uuid of session.activeTurn.steeredEchoes) {
+                this.trackOrphanCommand(session, uuid, "pending");
+            }
+        }
         // Capture the orphan-accounting lane before anything can await: the
         // consumer latches msgLifecycleV1 when it drains the first system/init,
         // which can happen DURING the awaited interrupt() below — the receipt
@@ -3884,7 +4359,7 @@ export class ClaudeAcpAgent {
             sessionId,
             update: {
                 sessionUpdate: "available_commands_update",
-                availableCommands: getAvailableSlashCommands(commands),
+                availableCommands: getAvailableSlashCommands(commands, session.terminalSlashCommands),
             },
         });
     }
@@ -4398,15 +4873,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),
                             }),
                         ],
                     },
@@ -4417,15 +4884,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),
                             }),
                         ],
                     },
@@ -5005,11 +5464,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
@@ -5441,7 +5910,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",
@@ -5453,6 +5926,7 @@ function getAvailableSlashCommands(commands) {
         "todos",
     ];
     return commands
+        .filter((command) => !terminalCommands?.includes(command.name))
         .map((command) => {
         const input = command.argumentHint
             ? {
@@ -5631,7 +6105,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" &&
@@ -5639,12 +6113,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 →
@@ -5655,7 +6171,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,
@@ -5664,7 +6180,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 } }
                 : {}),
@@ -5690,7 +6206,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",
@@ -5973,20 +6489,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),
@@ -6235,6 +6771,7 @@ export function runAcp() {
         .onRequest(methods.agent.session.prompt, (ctx) => runPromptWithCancellation(agent, ctx.params, ctx.signal))
         .onNotification(methods.agent.session.cancel, (ctx) => agent.cancel(ctx.params))
         .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));
     return { connection, agent };