@lucascouts/claude-agent-acp-plus 0.34.1 → 0.36.0

package/dist/acp-agent.js

@@ -22,6 +22,7 @@ import { createThinkingConfigOption, effectiveThinkingConfig, modelCanDisableThi
 import { applyLegacyUltracodeEffort, applyUltracodeReadback, applyUltracodeToggle, effortFlagSettings, isLegacyUltracodeEffort, isUltracodeAvailable, readUltracodeState, resolveUltracodeRequested, ULTRACODE_CONFIG_ID, ultracodeConfigOption, } from "./ultracode.js";
 import { deleteSessionIfStored } from "./session-delete.js";
 import { applyPlanUpdatesToOptions, createPlanUpdatesConfigOption, resolvePlanUpdatesAtSpawn, resolvePlanUpdatesRequested, TODO_TOOLS_ENV, } from "./plan-updates.js";
+import { planRemovedUpdate, planSessionUpdate, supportsPlanOperations } from "./keyed-plan.js";
 import { handleRewindCommand, parseRewindInvocation } from "./rewind-command.js";
 import { resolvePermissionMode, sessionAllowsBypass } from "./permissions/modes.js";
 import { normalizeDurablePermissionChangeSet } from "./permissions/normalization.js";
@@ -30,8 +31,8 @@ import { buildClaudePermissionPresentation } from "./permissions/presentation.js
 import { decodeClaudePermissionResponse } from "./permissions/response.js";
 import { activeUsageLimitMessage, airSessionFailureCapabilityMeta, assistantMessageText, createSessionFailureState, isSyntheticUsageLimitMessage, providerFailureCategory, SessionFailureController, sessionFailureMeta, supportsAirSessionFailures, } from "./session-failure-extension.js";
 import { AGENT_FILE_CHANGE_REPORT_CAPABILITY, agentFileChangeReportMeta, agentFileChangeReportRequestId, containsFileChangeAuditMarker, createFileChangeAuditSupport, createFileChangeAuditTurnState, FILE_CHANGE_AUDIT_SERVER_NAME, isFileChangeAuditReportPhase, isFileChangeAuditTool, supportsAgentFileChangeReport, } from "./file-change-audit.js";
-import { clientSupportsNotices, MAX_NOTICE_TITLE_LENGTH, normalizeNoticeText, noticeOrTranscriptUpdate, sentenceCase, splitNoticeText, } from "./session-notices.js";
-import { applyTaskCreate, applyTaskList, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, parseTaskListOutput, parseTaskUpdateOutput, planEntries, registerHookCallback, shellDescription, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
+import { clientSupportsNotices, collapseHookSpeaker, MAX_NOTICE_TITLE_LENGTH, normalizeNoticeText, noticeOrTranscriptUpdate, sentenceCase, splitNoticeText, } from "./session-notices.js";
+import { applyTaskCreate, applyTaskList, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, parseTaskListOutput, parseTaskUpdateOutput, planEntries, registerHookCallback, shellDescription, unregisterHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
 import { acceptedPlanToolResult, ExitPlanCoordinator, exitPlanModeRawOutput, isExitPlanInterruptionResult, observeExitPlanToolResults, } from "./exit-plan.js";
 import { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID, PLAN_UPDATES_CONFIG_ID, } from "./session-config-ids.js";
@@ -45,6 +46,7 @@ import { AccountUsageTracker } from "./account-usage.js";
 import { readFreshLimits, sharedSampleMaxAgeMs, writeLimits } from "./quota-cache.js";
 import { ACCOUNT_CONFIG_ID, accountForValue, accountInForce, createAccountConfigOption, envForAccount, readDeclaredAccounts, } from "./accounts.js";
 import { isUsageCommandText, structuredUsageMarkdown, syntheticLocalCommand, } from "./usage-markdown.js";
+import { STARTUP_FAILURE_RESULTS_ENV, startupFailureError } from "./startup-failure.js";
 export { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
 import { MODE_CONFIG_ID, SessionModeManager } from "./session-mode.js";
 import { TASKS_CONTRACT_VERSION, TASKS_META_KEY, normaliseStatus, TailPoller, TaskFeed, TaskFeedPublisher, } from "./task-feed.js";
@@ -418,30 +420,55 @@ function subagentLaunchOf(parentSessionId, session, message) {
         launcherTaskId: message.parent_task_id,
         toolUseId: message.tool_use_id,
         agentId: message.task_id,
-        title: name ?? message.subagent_type ?? message.description,
-        description: message.description,
+        ...subagentLabels(name, message.description, message.subagent_type),
         prompt,
         cancellable: typeof session.query.stopTask === "function",
     };
 }
+/**
+ * The RFD labels for a child (upstream #1479). The title is what tells siblings apart: the
+ * agent's name when it has one, else the task's short description (never the prompt), else its
+ * role. The description is the role, its `subagent_type`, unless the role is already the title.
+ * Before this, siblings of one type all read "Explore".
+ */
+export function subagentLabels(name, task, role) {
+    const text = (value) => (value && value.trim() ? value : undefined);
+    const agentRole = text(role);
+    const title = text(name) ?? text(task) ?? agentRole ?? "Subagent";
+    return { title, ...(agentRole && agentRole !== title ? { description: agentRole } : {}) };
+}
 /** A child read back from a transcript, in the shape `ChildSessionRouter`
  *  announces: the same title rule as a live launch (`subagentLaunchOf`). */
 function childLaunchOf(parentSessionId, session, toolUseId, record, input) {
     const text = (value) => (typeof value === "string" && value.trim() ? value : undefined);
-    const description = record.description ?? text(input.description) ?? "";
     return {
         parentSessionId,
         launcherTaskId: record.launcherAgentId,
         toolUseId,
         agentId: record.agentId,
-        title: record.name ?? text(input.name) ?? record.agentType ?? (description || "Subagent"),
-        description,
+        ...subagentLabels(record.name ?? text(input.name), record.description ?? text(input.description), record.agentType ?? text(input.subagent_type)),
         prompt: text(input.prompt),
         // History, not a task the CLI holds: no Stop until it runs again, when its
         // live launch advertises what the SDK can stop (design.md, Security).
         cancellable: false,
     };
 }
+/** Whether a permission request from `agentID` belongs to work that blocks the turn: the main
+ *  thread (no agent id), a foreground subagent, or a subagent launched by one. A task this
+ *  session never registered is not foreground work (upstream #1466, `blocksForeground`). */
+function blocksForeground(session, agentID) {
+    const seen = new Set();
+    for (let id = agentID; id !== undefined && !seen.has(id);) {
+        seen.add(id);
+        const task = session.liveBackgroundTasks.get(id);
+        if (!task)
+            return false;
+        if (task.backgrounded)
+            return false;
+        id = task.parentTaskId;
+    }
+    return true;
+}
 /** The text of a user message whose content is a string or one text block. */
 function userText(content) {
     if (typeof content === "string")
@@ -750,6 +777,16 @@ export function isReplayHiddenMetaMessage(message) {
 export function isLocalCommandMetadata(content) {
     return stripLocalCommandMetadata(content) === null;
 }
+/**
+ * True when CLI error text tells the user to sign in with `/login`. The CLI
+ * words this several ways — "Not logged in · Please run /login", "Not logged
+ * in · Run /login", "Login expired · Run /login to sign in again, or
+ * re-authenticate your Anthropic profile" — so match the "run /login"
+ * instruction rather than one sentence.
+ */
+export function isLoginRequiredText(text) {
+    return /\brun \/login\b/i.test(text);
+}
 /**
  * True for the synthetic assistant message the CLI injects into the transcript
  * when a turn fails authentication (e.g. "Not logged in · Please run /login",
@@ -762,9 +799,13 @@ export function isLocalCommandMetadata(content) {
  * session/load even after the user has logged back in.
  *
  * Takes the API message (`message.message`), which replay only knows as
- * `unknown`. The persisted record's structured `error: "authentication_failed"`
- * marker is stripped by `getSessionMessages`, so the synthetic model + text is
- * all both paths have to match on.
+ * `unknown`. The persisted record's structured `error` marker is stripped by
+ * `getSessionMessages`, and the CLI does not always set it to
+ * `authentication_failed` anyway: an expired login with no refresh token
+ * ("Login expired · Run /login to sign in again, …") arrives as
+ * `invalid_request`. So the synthetic model + text is what both paths match on.
+ * Usage-limit banners are excluded because some of them also mention `/login`
+ * (to switch accounts) and have their own handling.
  */
 export function isSyntheticLoginMessage(apiMessage) {
     if (!apiMessage || typeof apiMessage !== "object") {
@@ -778,7 +819,8 @@ export function isSyntheticLoginMessage(apiMessage) {
     return (!!block &&
         block.type === "text" &&
         typeof block.text === "string" &&
-        block.text.includes("Please run /login"));
+        isLoginRequiredText(block.text) &&
+        !isSyntheticUsageLimitMessage(apiMessage));
 }
 /**
  * Bridges {@link AcpClient} to the connection-scoped {@link AgentContext}
@@ -1483,13 +1525,14 @@ export class ClaudeAcpAgent {
         });
     }
     async publishTaskPlan(sessionId, taskState) {
-        await this.client.sessionUpdate({
-            sessionId,
-            update: {
-                sessionUpdate: "plan",
-                entries: taskStateToPlanEntries(taskState),
-            },
-        });
+        const keyed = supportsPlanOperations(this.clientCapabilities);
+        // An emptied list (a conversation reset) removes the keyed plan rather
+        // than leaving an empty one on screen; a legacy client gets the empty plan
+        // it always got.
+        const update = keyed && taskState.size === 0
+            ? planRemovedUpdate()
+            : planSessionUpdate(taskStateToPlanEntries(taskState), keyed);
+        await this.client.sessionUpdate({ sessionId, update });
     }
     /** This session's quota-window mapper, created on first use (see
      *  {@link Session.accountUsage} for why it lives on the Session). */
@@ -1702,6 +1745,44 @@ export class ClaudeAcpAgent {
         log(refreshed ? "published" : "nothing", coalesced ? "coalesced" : undefined);
         return { refreshed };
     }
+    /** Upstream #1464: a session notice when a client-provided MCP server reports `failed` or
+     *  `needs-auth` at init, once per server per session. Plus has no MCP OAuth flow, so a
+     *  `needs-auth` server is always reported; its tools stay unavailable until it is authenticated. */
+    async reportMcpServerStartupFailures(session, servers, supportsNotices, sendUpdate, sessionId) {
+        if (!servers?.length)
+            return;
+        const clientServers = new Set((session.creationParams?.mcpServers ?? []).map((server) => server.name));
+        for (const server of servers) {
+            if (!clientServers.has(server.name) || session.reportedMcpServers?.has(server.name)) {
+                continue;
+            }
+            let notice;
+            if (server.status === "failed") {
+                notice = {
+                    severity: "warning",
+                    title: `MCP server "${server.name}" failed to start`,
+                    description: "Its tools are unavailable in this session. Run /mcp for the error.",
+                };
+            }
+            else if (server.status === "needs-auth") {
+                notice = {
+                    severity: "info",
+                    title: `MCP server "${server.name}" needs authentication`,
+                    description: "Its tools are unavailable until the server is authenticated.",
+                };
+            }
+            else {
+                continue;
+            }
+            (session.reportedMcpServers ??= new Set()).add(server.name);
+            await sendUpdate({
+                sessionId,
+                update: noticeOrTranscriptUpdate(notice, supportsNotices, undefined, {
+                    claudeCode: { kind: "mcpServerStatus", server: server.name, status: server.status },
+                }),
+            });
+        }
+    }
     async publishGoalFromPrompt(sessionId, prompt, commandUuid) {
         const goalUpdate = goalUpdateFromPrompt(prompt);
         if (goalUpdate !== undefined) {
@@ -1948,6 +2029,11 @@ export class ClaudeAcpAgent {
     endTurnScope(session, turn, reason) {
         session.classifierGrants.clearOnce();
         this.finishFileChangeAudit(session, turn, reason);
+        // Every cancel path settles through here. The turn's foreground tasks end
+        // with it even when the CLI omits their closing event (F3, §5.3).
+        if (reason === "cancelled" && session.taskFeed && session.taskFeedPublisher) {
+            session.taskFeedPublisher.notify(session.taskFeed.onTurnCancelled());
+        }
     }
     /** Publish the audit terminal for every turn path that did not reach the
      *  report tool. The support flips the turn state synchronously before its
@@ -1986,6 +2072,10 @@ export class ClaudeAcpAgent {
         let lastAssistantTotalUsage = null;
         let lastAssistantUsage = null;
         let lastAssistantModel = null;
+        // A `rate_limit_event` that arrived before the turn had a context total to
+        // send it with (upstream #1534): with partial messages on, the SDK sends it
+        // ahead of the first assistant frame. It rides the turn's next usage_update.
+        let pendingRateLimit = null;
         // When the Claude SDK classifies a turn as failed (e.g. rate limit, auth
         // problem, billing), it sets a categorical `error` field on the
         // `SDKAssistantMessage` that precedes the final `result` message. We capture
@@ -2141,10 +2231,23 @@ export class ClaudeAcpAgent {
             await sessionFailures.clear((failure) => failure.recoveryPolicy === "next_attempt" && failure.turnId !== activeTurnId);
         };
         const internalErrorForClient = (data, rawDetail) => RequestError.internalError(data, supportsAirSessionFailures(this.clientCapabilities) ? undefined : rawDetail);
+        /** Attach a pending rate limit to a usage_update, once. A `_claude/rateLimit`
+         *  the update already carries wins, the same precedence upstream uses. */
+        const withPendingRateLimit = (update) => {
+            if (pendingRateLimit === null)
+                return update;
+            const rateLimit = pendingRateLimit;
+            pendingRateLimit = null;
+            return { ...update, _meta: { "_claude/rateLimit": rateLimit, ...(update._meta ?? {}) } };
+        };
         const resetTurnScratch = () => {
             lastAssistantTotalUsage = null;
             lastAssistantUsage = null;
             lastAssistantModel = null;
+            // A pending event belongs to the turn that measured it; one that found no
+            // usage_update to ride must not be attributed to the next turn. The
+            // tracker already remembers its status (R1.6).
+            pendingRateLimit = null;
             lastAssistantError = undefined;
             lastAssistantWasUsageLimit = false;
             lastAssistantFailureTitle = undefined;
@@ -3051,6 +3154,7 @@ export class ClaudeAcpAgent {
                                         }
                                     }
                                 }
+                                await this.reportMcpServerStartupFailures(session, message.mcp_servers, supportsNotices, sendUpdate, params.sessionId);
                                 break;
                             case "status": {
                                 // Compaction is reported as ONE tool lifecycle rather than the
@@ -3110,11 +3214,11 @@ export class ClaudeAcpAgent {
                                 session.contextUsedTokens = usedTokens ?? 0;
                                 await sendUpdate({
                                     sessionId: params.sessionId,
-                                    update: {
+                                    update: withPendingRateLimit({
                                         sessionUpdate: "usage_update",
                                         used: lastAssistantTotalUsage,
                                         size: session.contextWindowSize,
-                                    },
+                                    }),
                                 });
                                 break;
                             }
@@ -3474,9 +3578,10 @@ export class ClaudeAcpAgent {
                                     }
                                 }
                                 const severity = message.level === "warning" ? "warning" : "info";
+                                const transcriptContent = collapseHookSpeaker(message.content);
                                 const transcriptText = message.level === "info"
-                                    ? message.content
-                                    : `**${sentenceCase(message.level)}:** ${message.content}`;
+                                    ? transcriptContent
+                                    : `**${sentenceCase(message.level)}:** ${transcriptContent}`;
                                 await sendUpdate({
                                     sessionId: params.sessionId,
                                     update: noticeOrTranscriptUpdate({
@@ -3530,6 +3635,10 @@ export class ClaudeAcpAgent {
                                 session.liveBackgroundTasks.set(message.task_id, {
                                     parentToolUseId: message.tool_use_id,
                                     isSubagent: !!message.subagent_type,
+                                    ...(message.is_backgrounded !== undefined
+                                        ? { backgrounded: message.is_backgrounded }
+                                        : {}),
+                                    ...(message.parent_task_id ? { parentTaskId: message.parent_task_id } : {}),
                                 });
                                 if (message.subagent_type && session.activeTurn && !session.activeTurn.settled) {
                                     (session.activeTurn.spawnedTaskIds ??= new Set()).add(message.task_id);
@@ -3568,6 +3677,12 @@ export class ClaudeAcpAgent {
                                     this.logger.log(`[task/late-run] dropped=task_updated task=${message.task_id} run=${message.run_id}`);
                                     break;
                                 }
+                                // A task moved to the background no longer blocks the foreground (#1466).
+                                if (message.patch.is_backgrounded !== undefined) {
+                                    const task = session.liveBackgroundTasks.get(message.task_id);
+                                    if (task)
+                                        task.backgrounded = message.patch.is_backgrounded;
+                                }
                                 // terminal-status task_updated patch and a (deduplicated)
                                 // task_notification when a task settles, but only the patch is
                                 // guaranteed per transition — prune on it too so the registry
@@ -3847,7 +3962,7 @@ export class ClaudeAcpAgent {
                                         message.stop_reason === "refusal" ||
                                         ("result" in message &&
                                             message.is_error &&
-                                            message.result.includes("Please run /login"));
+                                            isLoginRequiredText(message.result));
                                     if (goalCommandFailed) {
                                         await this.publishGoal(params.sessionId, pendingGoalUpdate.previous ?? null);
                                     }
@@ -3973,7 +4088,7 @@ export class ClaudeAcpAgent {
                             if (lastAssistantTotalUsage !== null) {
                                 await sendUpdate({
                                     sessionId: params.sessionId,
-                                    update: {
+                                    update: withPendingRateLimit({
                                         sessionUpdate: "usage_update",
                                         used: lastAssistantTotalUsage,
                                         size: session.contextWindowSize,
@@ -3984,7 +4099,7 @@ export class ClaudeAcpAgent {
                                         ...(message.origin && {
                                             _meta: { "_claude/origin": message.origin },
                                         }),
-                                    },
+                                    }),
                                 });
                             }
                             if (session.cancelled) {
@@ -4008,7 +4123,7 @@ export class ClaudeAcpAgent {
                             // drained hold at their results is as good as the idle
                             // fallback.) Then stop: everything below is user-turn
                             // lifecycle, and an autonomous outcome must never touch it —
-                            // its is_error or "Please run /login" text would otherwise
+                            // its is_error or "run /login" text would otherwise
                             // failActive a live turn (the held one, or the user's next
                             // prompt) whose own result recorded a different outcome.
                             if (isAutonomousResult) {
@@ -4128,7 +4243,7 @@ export class ClaudeAcpAgent {
                             }
                             switch (message.subtype) {
                                 case "success": {
-                                    if (message.is_error && message.result.includes("Please run /login")) {
+                                    if (message.is_error && isLoginRequiredText(message.result)) {
                                         await failActiveWithSessionFailure("auth_required", RequestError.authRequired(), message.result);
                                         break;
                                     }
@@ -4391,11 +4506,11 @@ export class ClaudeAcpAgent {
                                 session.contextUsedTokens = nextUsage;
                                 await sendUpdate({
                                     sessionId: params.sessionId,
-                                    update: {
+                                    update: withPendingRateLimit({
                                         sessionUpdate: "usage_update",
                                         used: nextUsage,
                                         size: session.contextWindowSize,
-                                    },
+                                    }),
                                 });
                             }
                         }
@@ -4532,6 +4647,13 @@ export class ClaudeAcpAgent {
                             message.parent_tool_use_id === null &&
                             message.message.model === "<synthetic>" &&
                             compaction.hasDeliveredOutput) {
+                            if (isSyntheticUsageLimitMessage(message.message)) {
+                                lastAssistantWasUsageLimit = true;
+                                lastAssistantFailureTitle = assistantMessageText(message.message);
+                                if (message.error) {
+                                    lastAssistantError = message.error;
+                                }
+                            }
                             break;
                         }
                         // Snapshot the latest top-level assistant usage and model so the
@@ -4660,6 +4782,7 @@ export class ClaudeAcpAgent {
                             }
                         }
                         let content;
+                        let toolUseResult = message.type === "user" ? message.tool_use_result : undefined;
                         if (message.type === "assistant" && message.parent_tool_use_id === null) {
                             // Top-level assistant message: each text/thinking block may have
                             // already been streamed live as deltas. Diff each against what
@@ -4734,6 +4857,18 @@ export class ClaudeAcpAgent {
                             // `parentToolUseId` stamped by toAcpNotifications.
                             content = message.message.content.filter((item) => item.type !== "text" && item.type !== "thinking");
                         }
+                        else if (message.parent_tool_use_id !== null &&
+                            Array.isArray(message.message.content)) {
+                            // Upstream #1431 (#1389): a foreground fork inherits a placeholder result for its
+                            // own launch. It completed the Agent call and dropped its tracked state, so the
+                            // fork's real report, arriving later, was lost. Only the launching side completes
+                            // that call. The message-level sidecar cannot describe a remaining result once its
+                            // launch result is removed.
+                            const launchId = message.parent_tool_use_id;
+                            content = message.message.content.filter((block) => block.type !== "tool_result" || block.tool_use_id !== launchId);
+                            if (content.length !== message.message.content.length)
+                                toolUseResult = undefined;
+                        }
                         else {
                             content = message.message.content;
                         }
@@ -4761,7 +4896,7 @@ export class ClaudeAcpAgent {
                             taskState: session.taskState,
                             emittedToolCalls: session.emittedToolCalls,
                             messageId: messageIdForGrouping(message),
-                            toolUseResult: message.type === "user" ? message.tool_use_result : undefined,
+                            toolUseResult,
                             // On the wire since CLI 2.1.216 but not in SDKUserMessage's
                             // type, hence the cast. Validated by parseToolResultMeta.
                             toolResultMeta: message.type === "user"
@@ -4846,12 +4981,15 @@ export class ClaudeAcpAgent {
                         //
                         // Recorded OUTSIDE the emission guard below, and before it: the
                         // memory is fed by the event itself, not by our ability to forward
-                        // it, and before the first assistant message of a session that
-                        // guard is false. The forwarding itself is untouched (R1.8) — it
-                        // still sends `rate_limit_info` verbatim, still on the same
-                        // notification shape, still only when a context total exists.
+                        // it, and before the first assistant message of a turn that guard
+                        // is false. The forwarding still sends `rate_limit_info` verbatim on
+                        // the same notification shape (R1.8); when the turn has no context
+                        // total yet, it waits for the turn's next usage_update (#1534).
                         this.accountUsageTracker(session).recordMeasured(message.rate_limit_info);
-                        if (lastAssistantTotalUsage !== null) {
+                        if (lastAssistantTotalUsage === null) {
+                            pendingRateLimit = message.rate_limit_info;
+                        }
+                        else {
                             await sendUpdate({
                                 sessionId: params.sessionId,
                                 update: {
@@ -5378,9 +5516,9 @@ export class ClaudeAcpAgent {
         // here the client has asked us to close the session, so signalling abort is
         // appropriate; query.close() above has already torn the subprocess down.
         session.abortController.abort();
-        // A pending throttle, retry or reconcile timer must not send to a closed
-        // session.
-        session.taskFeedPublisher?.dispose();
+        // The publisher was disposed once, with its final flush, by
+        // closeQueryStream → retireTaskFeed above (or when the stream closed
+        // earlier). Disposing it again here used to drop that flush (F3).
         delete this.sessions[sessionId];
     }
     /** Tear down all active sessions. Called when the ACP connection closes. */
@@ -5510,16 +5648,6 @@ export class ClaudeAcpAgent {
             ? option.options.flatMap((o) => ("options" in o ? o.options : [o]))
             : [];
         let validValue = allValues.find((o) => o.value === params.value);
-        // The option's reported currentValue is always a valid target, even when
-        // it has no options entry: a session running an out-of-picker model
-        // (resumed onto an allowlist-excluded model, or a refusal fallback)
-        // reports a currentValue that isn't selectable, and a client
-        // round-tripping it must not get "Invalid value". It flows through the
-        // normal apply path below — re-asserting an already-current value is
-        // harmless and can repair SDK drift.
-        if (!validValue && option.currentValue === params.value) {
-            validValue = { value: params.value, name: params.value };
-        }
         // For model options, fall back to resolveModelPreference when the exact
         // value doesn't match.  This lets callers use human-friendly aliases like
         // "opus" or "sonnet" instead of full model IDs like "claude-opus-4-6".
@@ -5703,7 +5831,7 @@ export class ClaudeAcpAgent {
             if (replaySession && replayMessageId && message.uuid) {
                 replaySession.messageIdToUuid.set(replayMessageId, message.uuid);
             }
-            // The live prompt loop converts the synthetic "Please run /login"
+            // The live prompt loop converts the synthetic "run /login"
             // assistant message into an authRequired error instead of showing its
             // TUI-specific text; skip it on replay too (issue #863).
             if (message.type === "assistant" && isSyntheticLoginMessage(message.message)) {
@@ -6056,6 +6184,21 @@ export class ClaudeAcpAgent {
             }
             if (signal.aborted)
                 throw new Error("Tool use aborted");
+            // On `session/cancel` the client answers every open permission request
+            // `cancelled`, including those of a background subagent, which the
+            // cancel does not stop. Answer such a request with a denial so the
+            // subagent reads "the user refused" and goes on. Throwing instead makes
+            // Claude Code deny it as "Tool permission request failed".
+            if (response.outcome?.outcome === "cancelled" &&
+                this.sessions[sessionId] === session &&
+                !blocksForeground(session, agentID)) {
+                return {
+                    behavior: "deny",
+                    message: "User refused permission to run tool",
+                    toolUseID,
+                    decisionClassification: "user_reject",
+                };
+            }
             const decodedPermission = decodeClaudePermissionResponse(response, toolName, toolInput, toolUseID, permissionOptions, durableChangeSet);
             let permissionResult = decodedPermission.permissionResult;
             const autoFallback = this.sessionModes.applyPermissionFallback(session, permissionResult);
@@ -6103,18 +6246,20 @@ export class ClaudeAcpAgent {
     }
     /**
      * Handle elicitation requests that originate from MCP servers by forwarding
-     * them to the client over ACP. Modes the client did not advertise (or
-     * requests we can't represent) are declined.
+     * them to the client over ACP. Only the user's own decline reaches the MCP
+     * server as `decline`. A request the user never saw, because the client did
+     * not advertise its mode, we can't represent it, or the client answered with
+     * an error, is a `cancel`.
      */
     handleMcpElicitation(sessionId, support) {
         return async (request, { signal }) => {
             const isUrl = request.mode === "url";
             if ((isUrl && !support.url) || (!isUrl && !support.form)) {
-                return { action: "decline" };
+                return { action: "cancel" };
             }
             const createRequest = mcpElicitationToCreateRequest(request, sessionId);
             if (!createRequest) {
-                return { action: "decline" };
+                return { action: "cancel" };
             }
             try {
                 const response = await this.withPendingUserInput(sessionId, () => this.client.unstable_createElicitation(createRequest, signal));
@@ -6129,8 +6274,11 @@ export class ClaudeAcpAgent {
                 if (signal.aborted) {
                     return { action: "cancel" };
                 }
+                // The client answered with an error, e.g. -32602 for a form it cannot
+                // render, so the user never saw the request. MCP's `decline` means the
+                // user refused; `cancel` means they made no explicit choice.
                 this.logger.error(`Failed to forward MCP elicitation: ${error}`);
-                return { action: "decline" };
+                return { action: "cancel" };
             }
         };
     }
@@ -7188,6 +7336,7 @@ export class ClaudeAcpAgent {
             ...providerEnv,
             // Opt-in to session state events like when the agent is idle
             CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
+            ...STARTUP_FAILURE_RESULTS_ENV,
         };
         // Plan updates (story 062): the todo tools are on unless an env the user
         // wrote -- this spawn env or the settings tier the CLI applies after it --
@@ -7308,6 +7457,30 @@ export class ClaudeAcpAgent {
                         ],
                     }
                     : {}),
+                // Upstream #1496: a subagent's working directory, from its own SubagentStart hook,
+                // which Claude Code runs (and waits for) before the child's first model request.
+                ...(this.childSessions
+                    ? {
+                        SubagentStart: [
+                            ...(userProvidedOptions?.hooks?.SubagentStart || []),
+                            {
+                                hooks: [
+                                    async (input) => {
+                                        const childSessions = this.childSessions;
+                                        if (childSessions &&
+                                            typeof input.agent_id === "string" &&
+                                            typeof input.cwd === "string") {
+                                            await childSessions
+                                                .reportCwd(input.agent_id, input.cwd, params.cwd)
+                                                .catch((error) => this.logger.error(`Session ${sessionId}: failed to report subagent cwd: ${error}`));
+                                        }
+                                        return { continue: true };
+                                    },
+                                ],
+                            },
+                        ],
+                    }
+                    : {}),
                 TaskCreated: [
                     ...(userProvidedOptions?.hooks?.TaskCreated || []),
                     {
@@ -7376,13 +7549,23 @@ export class ClaudeAcpAgent {
             initializationResult = await q.initializationResult();
         }
         catch (error) {
+            // The CLI refused or exited: release the query so nothing of it is left behind (upstream
+            // closes it here too).
+            try {
+                q.close();
+            }
+            catch (closeError) {
+                this.logger.error(`Failed to close a query that did not initialize: ${closeError}`);
+            }
             if (creationOpts.resume &&
                 error instanceof Error &&
                 (error.message === "Query closed before response received" ||
                     error.message.includes("No conversation found with session ID"))) {
                 throw RequestError.resourceNotFound(sessionId);
             }
-            throw error;
+            // Upstream #1508: the CLI's own reason (bad proxy URL, wrong org sign-in, …) as an ACP
+            // error, instead of "Claude Code process exited with code 1".
+            throw startupFailureError(error) ?? error;
         }
         if (shouldHideClaudeAuth() &&
             initializationResult.account.subscriptionType &&
@@ -8019,6 +8202,21 @@ planUpdates) {
             }),
         },
     ];
+    // Upstream #1463: ACP requires `currentValue` to be one of `options`
+    // (agent-client-protocol#2557). A session can run a model the picker does not list --
+    // resumed onto a model the `availableModels` allowlist excludes, or switched by a refusal
+    // fallback -- so list it as its own entry. It is not added to `availableModels`, so the
+    // next rebuild after switching to a listed model drops it.
+    const modelOption = options[1];
+    const modelRows = modelOption.options;
+    if (!modelRows.some((row) => row.value === models.currentModelId)) {
+        const info = modelInfos.find((model) => model.value === models.currentModelId);
+        modelRows.push({
+            value: models.currentModelId,
+            name: info?.displayName || models.currentModelId,
+            ...(info?.description ? { description: info.description } : {}),
+        });
+    }
     // Add effort level option based on the currently selected model
     const currentModelInfo = modelInfos.find((m) => m.value === models.currentModelId);
     const supportedLevels = currentModelInfo?.supportsEffort
@@ -8626,17 +8824,26 @@ resumedSessionId) {
             // not the raw catalog upstream maps here: the filter is visibility-only,
             // so preference resolution and capability lookups elsewhere keep reading
             // the unfiltered catalog (R4.3).
-            availableModels: pickerModels.map((model) => ({
+            availableModels: withDistinctModelNames(pickerModels.map((model) => ({
                 modelId: model.value,
                 name: model.displayName,
                 description: model.description,
-            })),
+            }))),
             currentModelId: currentModel.value,
         },
         resumedContextWindow,
         resumedContextUsedTokens,
     };
 }
+/** Upstream #1286 (issue #1246): an allowlist can list an alias and pinned ids that inherit the
+ *  same SDK label, so a name-only picker shows identical rows. A name that occurs more than once
+ *  gets its model id appended; every row stays, and distinct names are unchanged. */
+export function withDistinctModelNames(models) {
+    const counts = new Map();
+    for (const model of models)
+        counts.set(model.name, (counts.get(model.name) ?? 0) + 1);
+    return models.map((model) => counts.get(model.name) === 1 ? model : { ...model, name: `${model.name} (${model.modelId})` });
+}
 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
@@ -8962,6 +9169,8 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
     const taskState = options?.taskState ?? new Map();
     const registerHooks = options?.registerHooks !== false;
     const supportsTerminalOutput = options?.clientCapabilities?._meta?.["terminal_output"] === true;
+    // §5.1: the task list as a keyed plan when the client applies them.
+    const keyedPlans = supportsPlanOperations(options?.clientCapabilities);
     if (typeof content === "string") {
         if (content.length === 0 || containsFileChangeAuditMarker(content)) {
             return [];
@@ -9063,10 +9272,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 else if (chunk.name === "TodoWrite") {
                     // @ts-expect-error - sometimes input is empty object or undefined
                     if (Array.isArray(chunk.input?.todos)) {
-                        update = {
-                            sessionUpdate: "plan",
-                            entries: planEntries(chunk.input),
-                        };
+                        update = planSessionUpdate(planEntries(chunk.input), keyedPlans);
                     }
                 }
                 else if (isTaskTool(chunk.name)) {
@@ -9144,6 +9350,26 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 }
                 break;
             }
+            case "advisor_tool_result": {
+                // Advisor results arrive in assistant content, including encrypted advice.
+                // Resolve the server tool through the normal result path without rendering
+                // opaque ciphertext. Server tools have no later PostToolUse hook to await.
+                const result = chunk.content;
+                unregisterHookCallback(chunk.tool_use_id);
+                output.push(...toAcpNotifications([
+                    {
+                        type: "tool_result",
+                        tool_use_id: chunk.tool_use_id,
+                        is_error: result.type === "advisor_tool_result_error",
+                        content: result.type === "advisor_result"
+                            ? result.text
+                            : result.type === "advisor_redacted_result"
+                                ? "Advisor guidance applied server-side."
+                                : `Advisor error: ${result.error_code}`,
+                    },
+                ], role, sessionId, toolUseCache, client, logger, options));
+                break;
+            }
             case "tool_result":
             case "tool_search_tool_result":
             case "web_fetch_tool_result":
@@ -9252,10 +9478,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                         }
                     }
                     if (shouldEmitTaskPlan) {
-                        update = {
-                            sessionUpdate: "plan",
-                            entries: taskStateToPlanEntries(taskState),
-                        };
+                        update = planSessionUpdate(taskStateToPlanEntries(taskState), keyedPlans);
                     }
                 }
                 else if (toolUse.name !== "TodoWrite") {
@@ -9316,7 +9539,6 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             case "container_upload":
             case "compaction":
             case "compaction_delta":
-            case "advisor_tool_result":
             case "fallback":
             case "mcp_tool_listing":
                 break;