@lucascouts/claude-agent-acp-plus 0.11.1 → 0.13.0

package/dist/acp-agent.js

@@ -14,7 +14,9 @@ import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createEli
 import { agentName } from "./agent-name.js";
 import { filterDeprecatedModels } from "./model-deprecation.js";
 import { SettingsManager } from "./settings.js";
+import { ContextCompactionLifecycle, contextCompactionMetadataFromBoundary, } from "./context-compaction.js";
 import { createThinkingConfigOption, effectiveThinkingConfig, resolveThinkingSelection, THINKING_CONFIG_ID, } from "./thinking-option.js";
+import { effortOptionValue, isUltracodeAvailable, isUltracodeValue, ULTRACODE_OPTION_NAME, ULTRACODE_OPTION_VALUE, ultracodeFlagSettings, } from "./ultracode.js";
 import { handleRewindCommand, parseRewindInvocation } from "./rewind-command.js";
 import { ALLOW_BYPASS, resolvePermissionMode } from "./permissions/modes.js";
 import { normalizeDurablePermissionChangeSet } from "./permissions/normalization.js";
@@ -29,6 +31,8 @@ import { acceptedPlanToolResult, ExitPlanCoordinator, executionDiagnostic, exitP
 import { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
 import { parseToolResultMeta } from "./tool-result-meta.js";
 import { AccountUsageTracker } from "./account-usage.js";
+import { ACCOUNT_CONFIG_ID, accountForValue, accountInForce, createAccountConfigOption, envForAccount, readDeclaredAccounts, } from "./accounts.js";
+import { isUsageCommandText, structuredUsageMarkdown } from "./usage-markdown.js";
 export { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
 import { MODE_CONFIG_ID, SessionModeManager } from "./session-mode.js";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
@@ -480,6 +484,14 @@ export class ClaudeAcpAgent {
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
      *  tests can shrink it. */
     forceCancelGraceMs = DEFAULT_FORCE_CANCEL_GRACE_MS;
+    /** The account selector's last choice, as a selector value (see
+     *  `accounts.ts`). Held on the AGENT, not on a session, because that is what
+     *  it governs: the account applies to sessions created after it is set, and
+     *  the thread that was on screen when the user chose keeps the account it
+     *  started under (D7 — a session id belongs to one account's local history,
+     *  so a live thread cannot be carried across a switch). `undefined` until a
+     *  selection is made, in which case the first declared account stands. */
+    selectedAccount;
     constructor(client, logger) {
         this.sessions = {};
         this.client = client;
@@ -1006,6 +1018,12 @@ export class ClaudeAcpAgent {
             session.fileChangeReportRequestIds.add(fileChangeReportRequestId);
             fileChangeAudit = createFileChangeAuditTurnState(fileChangeReportRequestId);
         }
+        // R2.3: exactly `/usage`, and nothing else in the prompt. A second block
+        // (an attached file, a second text part) is a model turn that happens to
+        // mention the command, not the local command itself.
+        const isUsageCommand = params.prompt.length === 1 &&
+            params.prompt[0]?.type === "text" &&
+            isUsageCommandText(params.prompt[0].text);
         session.titles.onPrompt(params.prompt);
         // Each prompt is a Turn whose deferred the persistent consumer settles once
         // the turn's outcome is known. `prompt()` owns no loop: it enqueues the
@@ -1014,6 +1032,9 @@ export class ClaudeAcpAgent {
         const turn = {
             promptUuid,
             isLocalOnlyCommand,
+            ...(isUsageCommand
+                ? { isUsageCommand: true, usageMarkdownAbort: new AbortController() }
+                : {}),
             ...(fileChangeAudit ? { fileChangeAudit } : {}),
             settled: false,
             resolve: () => { },
@@ -1309,11 +1330,6 @@ export class ClaudeAcpAgent {
         // stop_reason "refusal" and structured stop_details. We capture the
         // human-readable explanation so the terminal `result` can surface it.
         let lastRefusalExplanation = null;
-        // Tracks whether we're inside a compaction. The SDK emits the terminal
-        // `status` (compact_result success/failed) twice for a single failed
-        // compaction, and the two messages are indistinguishable — so we report the
-        // outcome only while a compaction is in progress, then clear this.
-        let compactionInProgress = false;
         // Anthropic API message id of the assistant message currently being
         // streamed, captured from `message_start` so the streamed chunks that follow
         // (whose delta events don't carry it) can all be tagged with the same,
@@ -1348,6 +1364,12 @@ export class ClaudeAcpAgent {
          *  recognizable by the `parentToolUseId` meta that toAcpNotifications
          *  stamps from `parent_tool_use_id`, and never reach the top-level feed
          *  as the turn's answer. */
+        /** Compaction as one ACP tool lifecycle, replacing the in-progress boolean
+         *  this consumer used to infer it from (story 010, R2.1/R2.2). Declared
+         *  ahead of `sendUpdate` because that chokepoint consults it; the closure
+         *  below only dereferences `sendUpdate` when an update is actually sent,
+         *  which is always after both bindings exist. */
+        const compaction = new ContextCompactionLifecycle((notification) => sendUpdate(notification));
         const sendUpdate = async (notification) => {
             const { update } = notification;
             if (isFileChangeAuditReportPhase(session.activeTurn?.fileChangeAudit) &&
@@ -1360,6 +1382,14 @@ export class ClaudeAcpAgent {
             }
             if (update.sessionUpdate === "agent_message_chunk") {
                 const claudeMeta = update._meta?.claudeCode;
+                // A failed manual compaction's error also arrives as assistant text;
+                // the tool lifecycle already carried it, so drop that one copy rather
+                // than report the same failure twice (R2.2).
+                if (!claudeMeta?.parentToolUseId &&
+                    update.content.type === "text" &&
+                    compaction.consumeDuplicateErrorOutput(update.content.text)) {
+                    return;
+                }
                 if (!claudeMeta?.parentToolUseId) {
                     session.emittedAssistantText = true;
                     session.titles.onAssistantText(update.content);
@@ -1412,7 +1442,6 @@ export class ClaudeAcpAgent {
             lastAssistantWasUsageLimit = false;
             lastAssistantFailureTitle = undefined;
             lastRefusalExplanation = null;
-            compactionInProgress = false;
             // Do NOT reset currentStreamMessageId or streamedBlocks here. Turn
             // activation can fire mid-message (the replayed user echo with
             // --replay-user-messages lands between a message's blocks); clearing the
@@ -1431,6 +1460,22 @@ export class ClaudeAcpAgent {
             if (session.activeTurn)
                 session.activeTurn.carriedUsage = undefined;
         };
+        /** Start this turn's structured `/usage` render, once, and hand back the
+         *  in-flight promise; undefined when the turn owns no render.
+         *
+         *  Started at ACTIVATION rather than when the output arrives, so the
+         *  bounded wait overlaps the command instead of following it: by the time
+         *  the CLI has printed its answer the report has usually already lost or
+         *  won its race, and the user waits for neither. */
+        const ensureUsageMarkdown = (turn) => {
+            if (!turn.isUsageCommand || !turn.usageMarkdownAbort) {
+                return undefined;
+            }
+            // `session.query` is read here rather than captured: a provider switch
+            // can replace it, and the render must ask the query that is live now.
+            turn.usageMarkdown ??= structuredUsageMarkdown(session.query, turn.usageMarkdownAbort.signal, this.logger);
+            return turn.usageMarkdown;
+        };
         /** Promote a queued turn to active: it becomes the one output is attributed
          *  to, and its scratch starts fresh. Clears the cancelled flag so a turn
          *  enqueued after a prior cancel isn't treated as cancelled. Also clears any
@@ -1442,6 +1487,7 @@ export class ClaudeAcpAgent {
         const activateTurn = (turn) => {
             session.activeTurn = turn;
             session.cancelled = false;
+            ensureUsageMarkdown(turn);
             session.pendingOrphanResults = 0;
             session.orphanCommands?.clear();
             // Two-phase sweep of registry entries the level signal ended (see
@@ -1480,12 +1526,20 @@ export class ClaudeAcpAgent {
          *
          *  But an echo-less result can also be an ORPHAN: cancel() settles+removes a
          *  queued turn whose user message was already pushed, so the SDK still runs
-         *  it and emits a result with no uuid to match. Promoting the head for an
+         *  it and emits a result with no echo to match. Promoting the head for an
          *  orphan would misattribute its stop reason/usage to an unrelated later
          *  prompt. `session.pendingOrphanResults` counts exactly how many such
          *  orphans are still expected (FIFO, they arrive before any live turn's
-         *  result), so we skip those and only promote once the count is drained. */
-        const ensureActiveTurn = () => {
+         *  result), so we skip those and only promote once the count is drained.
+         *
+         *  `resultUserMessageUuid` is the result's own join key (SDK 0.3.246+
+         *  echoes the triggering send's client uuid on results; absent on older
+         *  CLIs, synthetic/meta turns, and session-scoped failures). When present
+         *  it upgrades the map lane from positional heuristics to an exact match:
+         *  a stamp naming an orphaned command consumes the result outright, and a
+         *  stamp naming anything else positively refutes "this is a dead turn's
+         *  result", so the dup-over-loss one-skip must not eat it. */
+        const ensureActiveTurn = (resultUserMessageUuid) => {
             if (session.activeTurn) {
                 if (!isHeldOpen(session.activeTurn)) {
                     return;
@@ -1537,8 +1591,19 @@ export class ClaudeAcpAgent {
             // double-consume it. The unexpected-transition logging in the frame
             // handler is the tripwire for that class of drift.
             if (session.orphanCommands?.size) {
+                // Resolved BEFORE the drain below, which deletes every started/zombie
+                // entry: a stamp naming a "started" orphan would no longer be found
+                // afterwards, and the result would promote the head — misattributing
+                // a dead turn's outcome to a live prompt, the exact failure the map
+                // exists to prevent. The lookup order is load-bearing.
+                const stampedOrphanUuid = resultUserMessageUuid !== undefined && session.orphanCommands.has(resultUserMessageUuid)
+                    ? resultUserMessageUuid
+                    : undefined;
                 let consumedOrphanResult = false;
                 let oldestPending;
+                // The started/zombie drain applies regardless of the stamp: commands
+                // folded into the turn that emitted this result share it, and zombies'
+                // late results have already passed (or never existed).
                 for (const [uuid, state] of session.orphanCommands) {
                     if (state === "started" || state === "zombie") {
                         consumedOrphanResult = true;
@@ -1548,17 +1613,33 @@ export class ClaudeAcpAgent {
                         oldestPending ??= uuid;
                     }
                 }
-                if (consumedOrphanResult) {
+                if (stampedOrphanUuid !== undefined) {
+                    // Exact join: the result names an orphaned command. Delete the
+                    // matched entry even when it is still "pending" (its dispatch frame
+                    // was lost) and consume the result — no promotion.
+                    session.orphanCommands.delete(stampedOrphanUuid);
                     return;
                 }
-                if (oldestPending !== undefined) {
-                    // No dispatch was seen before this result, so it is very likely a
-                    // live turn's — but a lost "started" frame would mean it IS the
-                    // orphan's (dup-over-loss: prefer one wrong skip over
-                    // misattributing a dead turn's outcome to a live prompt). Grant
-                    // each pending entry exactly one skip, like the count lane did.
-                    session.orphanCommands.delete(oldestPending);
-                    return;
+                if (resultUserMessageUuid !== undefined) {
+                    // The stamp names a send that is NOT in the orphan map, so this is
+                    // a live turn's result: skip both the consumed-return (its folded
+                    // orphans were drained above, but the result itself still needs a
+                    // turn) and the dup-over-loss one-skip the stamp refutes, and fall
+                    // through to promote the head.
+                }
+                else {
+                    if (consumedOrphanResult) {
+                        return;
+                    }
+                    if (oldestPending !== undefined) {
+                        // No dispatch was seen before this result, so it is very likely a
+                        // live turn's — but a lost "started" frame would mean it IS the
+                        // orphan's (dup-over-loss: prefer one wrong skip over
+                        // misattributing a dead turn's outcome to a live prompt). Grant
+                        // each pending entry exactly one skip, like the count lane did.
+                        session.orphanCommands.delete(oldestPending);
+                        return;
+                    }
                 }
             }
             const head = firstUnsettledQueuedTurn();
@@ -1599,6 +1680,49 @@ export class ClaudeAcpAgent {
          *  spelling of "a prompt is pending" shared by the head promotion and
          *  the autonomous stretch-close guard. */
         const firstUnsettledQueuedTurn = () => (session.turnQueue ?? []).find((t) => !t.settled);
+        /** Claim the structured render for whichever turn is producing this local
+         *  command output. Three answers, and the caller must distinguish all
+         *  three:
+         *
+         *    undefined — not a `/usage` turn, or one of R2.4's three ways out
+         *                fired: publish `originalOutput` unchanged
+         *    string    — the render: publish it INSTEAD of `originalOutput`
+         *    null      — publish nothing (a duplicate of an already-replaced
+         *                frame, or a turn cancelled during the wait)
+         *
+         *  No content signature and no text parsing: which turn owns a render was
+         *  decided from the prompt, so a command whose output happens to look like
+         *  `/usage`'s can never be rewritten. */
+        const takeUsageMarkdown = async (originalOutput) => {
+            const turn = session.activeTurn ?? firstUnsettledQueuedTurn();
+            if (!turn) {
+                return undefined;
+            }
+            const pending = ensureUsageMarkdown(turn);
+            if (!pending) {
+                return undefined;
+            }
+            const markdown = await pending;
+            // That await can span the whole bounded wait, and a cancel landing inside
+            // it ends the turn. A cancelled turn publishes nothing — not the render,
+            // and not the original text either.
+            if (session.cancelled) {
+                return null;
+            }
+            if (markdown === null) {
+                return undefined;
+            }
+            if (turn.usageMarkdownDelivered) {
+                // One local command can reach the client through more than one SDK
+                // message shape. Suppress an exact mirror of the frame already
+                // replaced, but let a later, genuinely different frame (an
+                // interruption diagnostic, say) take the normal path.
+                return turn.usageOriginalOutput === originalOutput ? null : undefined;
+            }
+            turn.usageMarkdownDelivered = true;
+            turn.usageOriginalOutput = originalOutput;
+            return markdown;
+        };
         /** Whether any background subagent this turn spawned is still live —
          *  while true, the turn's settlement stays deferred so the subagent's
          *  output and permission requests land inside it (see
@@ -1667,6 +1791,9 @@ export class ClaudeAcpAgent {
             // Captured before the settled flip below (isHeldOpen tests !settled).
             const wasHeld = isHeldOpen(turn);
             turn.settled = true;
+            // The turn is over: abandon any structured `/usage` render still in
+            // flight rather than leaving it to run out its own clock (D5).
+            turn.usageMarkdownAbort?.abort();
             disarmForceCancel(session);
             session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
             session.activeTurn = null;
@@ -1699,6 +1826,7 @@ export class ClaudeAcpAgent {
             }
             this.finishFileChangeAudit(session, turn, "providerError");
             turn.settled = true;
+            turn.usageMarkdownAbort?.abort();
             session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
             session.activeTurn = null;
             streamedToolInputs.clear();
@@ -1747,6 +1875,7 @@ export class ClaudeAcpAgent {
                     this.finishFileChangeAudit(session, turn, "providerError");
                     const wasHeld = isHeldOpen(turn);
                     turn.settled = true;
+                    turn.usageMarkdownAbort?.abort();
                     if (wasHeld) {
                         // A held turn's answer already streamed and its outcome is
                         // recorded — a stream death during the post-answer hold is a
@@ -2072,50 +2201,43 @@ export class ClaudeAcpAgent {
                                 }
                                 break;
                             case "status": {
-                                // These banners count as delivered text (via sendUpdate), so
-                                // an echo-less turn that only ever emits them (e.g. `/compact`,
-                                // promoted at its own result) doesn't have its result text
-                                // re-emitted by the issue-#453 fallback.
+                                // Compaction is reported as ONE tool lifecycle rather than the
+                                // assistant-text banners this branch used to emit (R2.1). The
+                                // banners needed a boolean in-progress guard because the SDK
+                                // repeats the terminal `status` and the two copies are
+                                // indistinguishable here; the lifecycle owns that de-duplication
+                                // by phase instead, so the guard is gone rather than inert (R2.2).
+                                //
+                                // The SDK signals manual `/compact` completion with a status
+                                // message carrying `compact_result`, not the `compact_boundary`
+                                // message (which only fires when there's content to compact) —
+                                // so both frames must be able to close a lifecycle.
                                 if (message.status === "compacting") {
-                                    compactionInProgress = true;
-                                    await sendUpdate({
-                                        sessionId: message.session_id,
-                                        update: {
-                                            sessionUpdate: "agent_message_chunk",
-                                            content: { type: "text", text: "Compacting..." },
-                                        },
-                                    });
+                                    await compaction.start(message.session_id, message.uuid);
                                 }
-                                else if (message.compact_result === "success" && compactionInProgress) {
-                                    // The SDK signals manual `/compact` completion with a status
-                                    // message carrying `compact_result`, not the `compact_boundary`
-                                    // message (which only fires when there's content to compact).
-                                    compactionInProgress = false;
-                                    await sendUpdate({
-                                        sessionId: message.session_id,
-                                        update: {
-                                            sessionUpdate: "agent_message_chunk",
-                                            content: { type: "text", text: "\n\nCompacting completed." },
-                                        },
-                                    });
+                                else if (message.compact_result === "success") {
+                                    await compaction.finish(message.session_id, message.uuid, "completed");
                                 }
-                                else if (message.compact_result === "failed" && compactionInProgress) {
-                                    compactionInProgress = false;
-                                    const reason = message.compact_error ? `: ${message.compact_error}` : ".";
-                                    await sendUpdate({
-                                        sessionId: message.session_id,
-                                        update: {
-                                            sessionUpdate: "agent_message_chunk",
-                                            content: { type: "text", text: `\n\nCompacting failed${reason}` },
-                                        },
+                                else if (message.compact_result === "failed") {
+                                    await compaction.finish(message.session_id, message.uuid, "failed", {
+                                        ...(message.compact_error ? { error: message.compact_error } : {}),
                                     });
                                 }
                                 break;
                             }
                             case "compact_boundary": {
+                                // This is the only frame carrying the token counts, and it
+                                // arrives AFTER the terminal `status` — so it enriches the
+                                // lifecycle rather than reporting an outcome again
+                                // (`enrichTerminal`): the update omits `status`, leaving exactly
+                                // one terminal transition the client can see (R2.2). It also
+                                // stands alone when no `status` preceded it (an automatic
+                                // compaction, or a replay that dropped the opening frame).
+                                const compactMetadata = message.compact_metadata;
+                                await compaction.finish(message.session_id, message.uuid, "completed", compactMetadata ? contextCompactionMetadataFromBoundary(compactMetadata) : {}, true);
                                 // Refresh the displayed usage immediately so the client doesn't
                                 // keep showing the stale pre-compaction size (e.g. "944k/1m")
-                                // right after the user sees "Compacting completed", which is
+                                // right after the compaction tool call completes, which is
                                 // confusing and wrong.
                                 //
                                 // Prefer the SDK's authoritative post-compaction `used` via
@@ -2130,10 +2252,6 @@ export class ClaudeAcpAgent {
                                 // `size` keeps coming from session.contextWindowSize —
                                 // compaction frees occupancy, it doesn't change the model's
                                 // window.
-                                //
-                                // The "Compacting completed." text is emitted from the `status`
-                                // handler (keyed on `compact_result`), not here, so the failure
-                                // path gets a message too.
                                 const usedTokens = await fetchContextUsedTokens(session.query, this.logger);
                                 lastAssistantUsage = null;
                                 lastAssistantTotalUsage = usedTokens ?? 0;
@@ -2149,11 +2267,24 @@ export class ClaudeAcpAgent {
                                 break;
                             }
                             case "local_command_output": {
+                                // A failed `/compact` also prints its error here; the tool
+                                // lifecycle already carried it, so consume that one duplicate
+                                // (matched by text, once) without hiding other command output.
+                                if (compaction.consumeDuplicateErrorOutput(message.content)) {
+                                    break;
+                                }
+                                // R2.3/R2.4: a `/usage` turn publishes its structured render
+                                // here instead; anything else, and any way out, publishes the
+                                // CLI's own text byte-for-byte.
+                                const usageMarkdown = await takeUsageMarkdown(message.content);
+                                if (usageMarkdown === null) {
+                                    break;
+                                }
                                 await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "agent_message_chunk",
-                                        content: { type: "text", text: message.content },
+                                        content: { type: "text", text: usageMarkdown ?? message.content },
                                     },
                                 });
                                 break;
@@ -2191,6 +2322,10 @@ export class ClaudeAcpAgent {
                                     // the interrupted turn's tokens entirely (issue #844). Zero
                                     // when the cancel pre-empted the result (wedge/force-cancel).
                                     if (session.cancelled && session.activeTurn && !session.activeTurn.settled) {
+                                        // An interrupt can pre-empt the result entirely, so the
+                                        // lifecycle's own reset there never ran; close it here or a
+                                        // half-open compaction would leak into the next turn.
+                                        compaction.reset();
                                         settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
                                         // An interrupt can pre-empt the turn's result entirely
                                         // (nothing ran the result-case `finally`), so close the
@@ -2253,6 +2388,9 @@ export class ClaudeAcpAgent {
                                     else if (!session.cancelled &&
                                         session.activeTurn &&
                                         !session.activeTurn.settled) {
+                                        // Same reason as the cancelled branch: this turn will never
+                                        // reach the result that would have reset the lifecycle.
+                                        compaction.reset();
                                         // Deliberately only the ACTIVE turn: a queued turn that
                                         // was never echoed is NOT failed here, because an idle
                                         // can legitimately precede the SDK picking up freshly
@@ -2668,7 +2806,7 @@ export class ClaudeAcpAgent {
                             // the map in that case).
                             if (!isAutonomousResult) {
                                 recordResultForOrphanCommands();
-                                ensureActiveTurn();
+                                ensureActiveTurn(message.user_message_uuid);
                                 // 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
@@ -2699,6 +2837,12 @@ export class ClaudeAcpAgent {
                             // through the early break below, which the gated `finally`
                             // leaves alone).
                             const deliveredAssistantText = session.emittedAssistantText;
+                            // The deleted "Compacting…" banners counted as delivered text
+                            // simply by going through sendUpdate; tool calls don't, so a turn
+                            // that ONLY compacted (e.g. `/compact`, promoted at its own
+                            // result) needs this to keep its result text from being re-emitted
+                            // by the issue-#453 fallback below.
+                            const deliveredCompactionOutput = compaction.hasDeliveredOutput;
                             // Every user-turn result terminates a turn (settle, reject, or
                             // orphan skip) and the SDK follows it with a trailing
                             // `session_state_changed: idle` — record the debt so the idle
@@ -2945,9 +3089,19 @@ export class ClaudeAcpAgent {
                                     // the fallback there. (Autonomous results never get here —
                                     // they exit at the early break above — so no background
                                     // prose can be injected into the feed.)
-                                    if (session.activeTurn?.isLocalOnlyCommand ||
-                                        (!deliveredAssistantText && (message.usage.output_tokens ?? 0) === 0)) {
-                                        for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, session.toolUseCache, this.client, this.logger)) {
+                                    const shouldForwardResult = session.activeTurn?.isLocalOnlyCommand ||
+                                        (!deliveredAssistantText &&
+                                            !deliveredCompactionOutput &&
+                                            (message.usage.output_tokens ?? 0) === 0);
+                                    if (shouldForwardResult) {
+                                        // A `/usage` turn whose output arrives only on the result.
+                                        // Claiming it here also stops the raw text following a
+                                        // render already published from another message shape.
+                                        const usageMarkdown = await takeUsageMarkdown(message.result);
+                                        if (usageMarkdown === null) {
+                                            break;
+                                        }
+                                        for (const notification of toAcpNotifications(usageMarkdown ?? message.result, "assistant", params.sessionId, session.toolUseCache, this.client, this.logger)) {
                                             await sendUpdate(notification);
                                         }
                                     }
@@ -3022,6 +3176,11 @@ export class ClaudeAcpAgent {
                         finally {
                             if (!isAutonomousResult) {
                                 session.emittedAssistantText = false;
+                                // A result closes this turn's compaction lifecycle. Reset here
+                                // rather than at idle: an owed idle from this turn can arrive
+                                // after the next turn has already started, and would erase that
+                                // turn's compaction state instead of its own.
+                                compaction.reset();
                                 // R1.2: a user turn's terminal result is the moment consumption
                                 // actually changed, so refresh the account quota windows here —
                                 // in the `finally`, which is the one point EVERY exit from this
@@ -3042,6 +3201,17 @@ export class ClaudeAcpAgent {
                         break;
                     }
                     case "stream_event": {
+                        // Compaction streams as its own block type. The deltas carry the
+                        // generated summary, which stays internal to the agent — all the
+                        // client gets is one keep-alive on the open tool call, so a long
+                        // compaction doesn't look stalled.
+                        const isCompactionProgress = (message.event.type === "content_block_start" &&
+                            message.event.content_block.type === "compaction") ||
+                            (message.event.type === "content_block_delta" &&
+                                message.event.delta.type === "compaction_delta");
+                        if (isCompactionProgress) {
+                            await compaction.heartbeat(message.session_id, message.uuid);
+                        }
                         // `message_start` carries the Anthropic API message id; capture it
                         // so the streamed chunks that follow (whose delta events don't carry
                         // it) can all be tagged with the same, replay-stable id.
@@ -3264,6 +3434,18 @@ export class ClaudeAcpAgent {
                         if (session.cancelled) {
                             break;
                         }
+                        // Synthetic assistant frames carry the CLI's local-command output.
+                        // On resume the SDK can replay a stale frame from an earlier compact
+                        // attempt after a later compaction completed. Scope the suppression
+                        // to the compaction lifecycle and the synthetic frame itself rather
+                        // than to the owning turn: one model turn may compact more than
+                        // once, and its real assistant response must still be delivered.
+                        if (message.type === "assistant" &&
+                            message.parent_tool_use_id === null &&
+                            message.message.model === "<synthetic>" &&
+                            compaction.hasDeliveredOutput) {
+                            break;
+                        }
                         // Snapshot the latest top-level assistant usage and model so the
                         // next `result` can emit a usage_update tied to the right context
                         // window. Subagent messages are excluded to keep the snapshot
@@ -3302,7 +3484,13 @@ export class ClaudeAcpAgent {
                             message.message.content.includes("<local-command-stdout>")) {
                             const stripped = stripLocalCommandMetadata(message.message.content);
                             if (typeof stripped === "string") {
-                                for (const notification of toAcpNotifications(stripped, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
+                                // The usual shape for a real `/usage`: the comment above names
+                                // it as one of the commands the CLI wraps in these markers.
+                                const usageMarkdown = await takeUsageMarkdown(stripped);
+                                if (usageMarkdown === null) {
+                                    break;
+                                }
+                                for (const notification of toAcpNotifications(usageMarkdown ?? stripped, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
                                     clientCapabilities: this.clientCapabilities,
                                     parentToolUseId: message.parent_tool_use_id,
                                     cwd: session.cwd,
@@ -3643,6 +3831,11 @@ export class ClaudeAcpAgent {
             await session.queryRecreateInFlight;
         }
         session.cancelled = true;
+        // Every turn's structured `/usage` render is abandoned here — the queue
+        // still holds the active turn at this point, so one sweep covers both.
+        for (const turn of session.turnQueue ?? []) {
+            turn.usageMarkdownAbort?.abort();
+        }
         session.pendingExitPlanModeInterruption = undefined;
         session.pendingExitPlanContextReset = undefined;
         // The stream already ended (see closeQueryStream): every in-flight turn was
@@ -3685,8 +3878,10 @@ export class ClaudeAcpAgent {
             }
             // Each removed queued turn's user message was already pushed to the SDK,
             // which processes input FIFO and will still emit a result for it with no
-            // uuid to match. Track those so the consumer skips them (see
-            // ensureActiveTurn) rather than misattributing them to the head.
+            // user echo to match (0.3.246+ CLIs do stamp results with the
+            // triggering send's user_message_uuid, which ensureActiveTurn uses as
+            // an exact join when present). Track those so the consumer skips them
+            // (see ensureActiveTurn) rather than misattributing them to the head.
             // msg_lifecycle_v1 CLIs get per-uuid tracking drained by the command's
             // own terminal lifecycle frame — exact under command coalescing, where
             // N queued commands fold into ONE turn emitting one result and a plain
@@ -4611,14 +4806,28 @@ export class ClaudeAcpAgent {
             // (R1.6).
             session.thinkingEnabled ??
                 effectiveThinkingConfig(undefined, process.env.MAX_THINKING_TOKENS, this.logger) !==
-                    undefined);
+                    undefined, {
+                // The new model decides whether the entry renders at all; the session's
+                // retained intent decides whether it renders selected. A model without
+                // `xhigh` drops the entry, and `validEffort` then falls back for it the
+                // same way it does for any unsupported level.
+                available: isUltracodeAvailable(newModelInfo?.supportsEffort ? (newModelInfo.supportedEffortLevels ?? []) : [], { disableWorkflows: session.workflowsDisabled }),
+                enabled: session.ultracode,
+            }, {
+                disableWorkflows: session.workflowsDisabled,
+                // Threaded for the same reason Thinking is (R1.7): an option not
+                // passed through this rebuild silently drops from the picker on
+                // every model switch. The account is model-independent, so the row
+                // and its selection survive unchanged.
+                accounts: session.declaredAccounts,
+                currentAccount: session.currentAccount,
+            });
             // Sync effort with the SDK if it changed after the model switch
             const newEffortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
             const newEffort = typeof newEffortOpt?.currentValue === "string" ? newEffortOpt.currentValue : undefined;
             if (newEffort !== currentEffort) {
-                await session.query.applyFlagSettings({
-                    effortLevel: toSdkEffortLevel(newEffort),
-                });
+                await session.query.applyFlagSettings(ultracodeFlagSettings(newEffort));
+                session.ultracode = isUltracodeValue(newEffort);
             }
             // Emit current_mode_update only after session.modes AND
             // session.configOptions have been fully reconciled. This way, a failure
@@ -4642,12 +4851,34 @@ export class ClaudeAcpAgent {
             session.currentAgent = value;
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
         }
+        else if (configId === ACCOUNT_CONFIG_ID) {
+            // Resolve BEFORE recording anything: an account nobody declared must
+            // leave the session exactly as it was. `setSessionConfigOption`'s shared
+            // validation already refuses a value that is not among the option's
+            // entries; this second check covers the one path that bypasses it (a
+            // client round-tripping `currentValue`) and keeps the refusal here
+            // rather than in a caller (R6.3).
+            const account = accountForValue(session.declaredAccounts ?? [], value);
+            if (!account) {
+                throw new Error(`Invalid value for config option ${configId}: ${value}`);
+            }
+            // No SDK call, and no query recreate: the account is applied through the
+            // per-session `env` at query CREATION (D2/D9 — the SDK already accepts
+            // one, so no Zed patch is involved), and this session's query keeps the
+            // account it was created under (D7).
+            this.selectedAccount = value;
+            session.currentAccount = value;
+            session.accountEnv = envForAccount(account);
+            session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
+        }
         else {
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
             if (configId === EFFORT_CONFIG_ID) {
-                await session.query.applyFlagSettings({
-                    effortLevel: toSdkEffortLevel(value),
-                });
+                // Both keys, always. Selecting a plain level after Ultracode must CLEAR
+                // the flag, and only an explicit `null` clears it — see
+                // `ultracodeFlagSettings`.
+                await session.query.applyFlagSettings(ultracodeFlagSettings(value));
+                session.ultracode = isUltracodeValue(value);
             }
         }
     }
@@ -4806,11 +5037,15 @@ export class ClaudeAcpAgent {
                 // read post-init, so a setter update that landed during the init
                 // await is already included.
                 const effortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
-                const effortLevel = typeof effortOpt?.currentValue === "string"
-                    ? toSdkEffortLevel(effortOpt.currentValue)
-                    : null;
+                const effortValue = typeof effortOpt?.currentValue === "string" ? effortOpt.currentValue : undefined;
+                const { effortLevel, ultracode } = ultracodeFlagSettings(effortValue);
+                // Only the positive case is re-applied: the replacement's flag layer
+                // starts empty, so clearing a key that was never set would be a control
+                // request that says nothing. `ultracode` is sent WITH its level rather
+                // than alone — the SDK requires an xhigh-capable model for it, and a
+                // flag layer carrying one half of the pair is a state no picker names.
                 if (effortLevel !== null) {
-                    await replacement.applyFlagSettings({ effortLevel });
+                    await replacement.applyFlagSettings(ultracode === true ? { effortLevel, ultracode: true } : { effortLevel });
                 }
                 const supportsFastMode = session.modelInfos.find((m) => m.value === session.models.currentModelId)
                     ?.supportsFastMode ?? false;
@@ -5234,9 +5469,28 @@ export class ClaudeAcpAgent {
                 env: { ...baseSettings?.env, ...providerEnv },
             };
         }
+        // The account this session runs under (R6.3): the selector's last choice
+        // when it names a declared account, else the first declared one. Read from
+        // the resolved settings, because accounts are DECLARED, never discovered
+        // (D4) — nothing here scans a home directory for credential stores. With
+        // none declared there is no overlay and the process's own configuration
+        // home stands, which is exactly the behavior that predates this option.
+        const declaredAccounts = readDeclaredAccounts(settingsManager.getSettings(), this.logger);
+        const accountEntry = accountInForce(declaredAccounts, this.selectedAccount);
+        // The SESSION's account home, never the ADAPTER's (D3): this overlay is
+        // handed to the SDK per session and to nothing else. `process.env` is not
+        // mutated — `CLAUDE_CONFIG_DIR` is read once into a module-level constant
+        // that `settings.ts` uses to find the adapter's OWN settings.json, so a
+        // mutation would be seen by some readers and not others.
+        const accountEnv = accountEntry ? envForAccount(accountEntry.account) : undefined;
         const env = {
             ...process.env,
             ...userProvidedOptions?.env,
+            // After the client-supplied env: the selector is a live user choice,
+            // and an agent entry that pinned CLAUDE_CONFIG_DIR is precisely the
+            // "account as a second agent" shape this option replaces (D1). Before
+            // the provider routing, which sets ANTHROPIC_* and never this key.
+            ...accountEnv,
             // Client-managed LLM routing: `providers/set` config wins, else the
             // legacy gateway auth request. Routing is baked into the query at
             // creation; provider updates recreate loaded queries between turns.
@@ -5500,6 +5754,7 @@ export class ClaudeAcpAgent {
             useBooleanOption: clientSupportsBooleanConfigOptions(this.clientCapabilities),
             disabledReason: fastModeDisabledReason,
         };
+        const workflowsDisabled = settingsManager.getSettings().disableWorkflows === true;
         const configOptions = buildConfigOptions(modes, models, 
         // Catalog-based (see `modelInfos` above), matching the model-switch
         // rebuild (which passes `session.modelInfos`): `buildConfigOptions`
@@ -5513,15 +5768,31 @@ export class ClaudeAcpAgent {
         // effectiveThinkingConfig(undefined, MAX_THINKING_TOKENS) from above, so
         // reusing it avoids re-parsing (and re-logging an invalid) env var —
         // exactly one error log per query creation.
-        thinking !== undefined);
+        thinking !== undefined, {
+            // Seeded from settings, not inferred from the level: `Settings.ultracode`
+            // is what the user (or a `--settings` payload) actually asked for, while
+            // `xhigh` on its own is a legitimate selection that is not Ultracode.
+            available: isUltracodeAvailable(currentModelInfo?.supportsEffort ? (currentModelInfo.supportedEffortLevels ?? []) : [], { disableWorkflows: workflowsDisabled }),
+            enabled: settingsManager.getSettings().ultracode === true,
+        }, {
+            disableWorkflows: workflowsDisabled,
+            // Both halves of the selector, resolved above alongside the env they
+            // produced — so the row the client renders and the configuration
+            // directory the query was actually started with cannot disagree.
+            accounts: declaredAccounts,
+            currentAccount: accountEntry?.value,
+        });
         // Apply the initial effort level to the SDK so it matches the UI default
         const initialEffort = configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
+        // The picker's resolved value, not the raw setting: `buildConfigOptions`
+        // has already dropped Ultracode if this model cannot reach `xhigh`, and the
+        // session must track what is displayed rather than what was requested.
+        const initialUltracode = typeof initialEffort?.currentValue === "string" &&
+            isUltracodeValue(initialEffort.currentValue);
         if (initialEffort &&
             typeof initialEffort.currentValue === "string" &&
             initialEffort.currentValue !== "default") {
-            await q.applyFlagSettings({
-                effortLevel: toSdkEffortLevel(initialEffort.currentValue),
-            });
+            await q.applyFlagSettings(ultracodeFlagSettings(initialEffort.currentValue));
         }
         // Seed the context window WITHOUT any extra IPC on the session/new path.
         // On session/load, the resumed session's own `getContextUsage` report — a
@@ -5586,6 +5857,11 @@ export class ClaudeAcpAgent {
             configOptions,
             agents,
             currentAgent,
+            ultracode: initialUltracode,
+            workflowsDisabled,
+            declaredAccounts,
+            currentAccount: accountEntry?.value,
+            accountEnv,
             fastModeEnabled,
             fastModeDisabledReason,
             abortController,
@@ -5811,18 +6087,6 @@ function isValidBaseUrl(baseUrl) {
     }
     return parsed.protocol === "http:" || parsed.protocol === "https:";
 }
-// Translate a UI effort value into the flag-layer payload. The SDK
-// shallow-merges `applyFlagSettings`, drops `undefined` during JSON transport,
-// and only clears a key when an explicit `null` is sent — see
-// `applyFlagSettings` in @anthropic-ai/claude-agent-sdk. Mapping both the
-// `"default"` sentinel and `undefined` (effort option absent for the model) to
-// `null` ensures any previously-applied flag is actually cleared. Typed as
-// `EffortLevel` (not `Settings["effortLevel"]`): the picker offers whatever
-// `supportedEffortLevels` reports, which includes the session-scoped `"max"`
-// that the persisted Settings shape deliberately excludes.
-function toSdkEffortLevel(value) {
-    return value === undefined || value === "default" ? null : value;
-}
 // `supportedAgents()` always returns Claude Code's built-in subagents — the
 // ones used for Task-tool delegation (Explore, Plan, etc.) — even when the user
 // has configured none of their own. Those aren't meaningful *main-thread*
@@ -5962,7 +6226,18 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
  *  (`intent ?? (effectiveThinkingConfig(undefined, env, logger) !== undefined)`).
  *  Both session call sites always supply it (R1.1); `undefined` (direct
  *  callers/tests) omits the row. */
-thinkingEnabled) {
+thinkingEnabled, 
+/** Display state for the Ultracode entry of the effort picker. Omitted by
+ *  direct callers/tests, in which case availability is derived from
+ *  `settings` and the entry renders unselected. */
+ultracode, 
+/** Resolved session settings, read for `disableWorkflows` — the half of the
+ *  Ultracode gate that is not a model capability — and, alongside them, the
+ *  declared accounts plus the one in force, which decide whether an account
+ *  selector is advertised at all (R6.1/R6.2). `accounts` is not a field of
+ *  the SDK's `Settings`, so it is carried beside them rather than picked
+ *  from them. */
+settings) {
     const options = [
         SessionModeManager.configOption(modes),
         {
@@ -5995,6 +6270,11 @@ thinkingEnabled) {
         ? (currentModelInfo.supportedEffortLevels ?? [])
         : [];
     if (supportedLevels.length > 0) {
+        // Ultracode rides the effort picker as one extra entry past the last level,
+        // which is where the VS Code extension draws it too. It is NOT a level (see
+        // `ultracode.ts`): the entry stands for `xhigh` plus workflow orchestration,
+        // and it is offered only when both halves are reachable.
+        const ultracodeAvailable = ultracode?.available ?? isUltracodeAvailable(supportedLevels, settings);
         const effortOptions = [
             { value: "default", name: "Default" },
             ...supportedLevels.map((level) => ({
@@ -6004,9 +6284,21 @@ thinkingEnabled) {
                     .map((part) => (part ? part.charAt(0).toUpperCase() + part.slice(1) : part))
                     .join(" "),
             })),
+            ...(ultracodeAvailable
+                ? [{ value: ULTRACODE_OPTION_VALUE, name: ULTRACODE_OPTION_NAME }]
+                : []),
         ];
-        const includes = (l) => l === "default" || supportedLevels.includes(l);
-        const validEffort = currentEffortLevel && includes(currentEffortLevel) ? currentEffortLevel : "default";
+        const includes = (l) => l === "default" ||
+            supportedLevels.includes(l) ||
+            (ultracodeAvailable && l === ULTRACODE_OPTION_VALUE);
+        // `effortOptionValue` resolves the flag against the level BEFORE validation,
+        // so an Ultracode session on a model that dropped `xhigh` falls back to
+        // "Default" through the same path any unsupported level does.
+        const displayedEffort = effortOptionValue(currentEffortLevel, {
+            available: ultracodeAvailable,
+            enabled: ultracode?.enabled ?? false,
+        });
+        const validEffort = displayedEffort && includes(displayedEffort) ? displayedEffort : "default";
         options.push({
             id: EFFORT_CONFIG_ID,
             name: "Effort",
@@ -6050,6 +6342,15 @@ thinkingEnabled) {
             ],
         });
     }
+    // The account selector, last because it is the least often touched of the
+    // rows and the only one that governs the NEXT thread rather than this one.
+    // `createAccountConfigOption` returns undefined below two declared accounts,
+    // so the row is genuinely absent there rather than present and empty (D8,
+    // R6.2).
+    const accountOption = createAccountConfigOption(settings?.accounts ?? [], settings?.currentAccount);
+    if (accountOption) {
+        options.push(accountOption);
+    }
     return options;
 }
 // Claude Code CLI persists display strings like "opus[1m]" in settings,