@lucascouts/claude-agent-acp-plus 0.26.0 → 0.28.0

package/dist/acp-agent.js

@@ -19,7 +19,7 @@ import { filterSupersededModels } from "./model-recency.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 { applyLegacyUltracodeEffort, applyUltracodeReadback, applyUltracodeToggle, effortFlagSettings, isLegacyUltracodeEffort, isUltracodeAvailable, readUltracodeState, resolveUltracodeRequested, ULTRACODE_CONFIG_ID, ultracodeConfigOption, } from "./ultracode.js";
 import { handleRewindCommand, parseRewindInvocation } from "./rewind-command.js";
 import { resolvePermissionMode, sessionAllowsBypass } from "./permissions/modes.js";
 import { normalizeDurablePermissionChangeSet } from "./permissions/normalization.js";
@@ -152,6 +152,28 @@ export const TASKS_OUTPUT_METHOD = "_claude/tasks/output";
 export const TASKS_CAPABILITY_KEY = TASKS_META_KEY;
 /** Version 2 (story 041) adds `hasOutput`, `tail` and `_claude/tasks/output`. */
 export const TASKS_CAPABILITY_VERSION = TASKS_CONTRACT_VERSION;
+/** Refresh the account quota windows of one session now, on demand. Params
+ *  {@link UsageRefreshRequest}, result {@link UsageRefreshResponse}. The windows
+ *  themselves arrive the way they always do — one `usage_update` per window,
+ *  carrying `_meta["_claude/rateLimit"]` — before the response does. */
+export const USAGE_REFRESH_METHOD = "_claude/usage/refresh";
+/** `agentCapabilities._meta` key advertising {@link USAGE_REFRESH_METHOD}. A
+ *  client gates on this, never on the agent's name (see
+ *  {@link TASKS_CAPABILITY_KEY}). */
+export const USAGE_CAPABILITY_KEY = "_claude/usage";
+export const USAGE_CAPABILITY_VERSION = 1;
+/** How old a shared quota sample may be and still answer an on-demand refresh.
+ *
+ *  The client asks on every hover of the context ring, so this is the knob that
+ *  trades freshness against cost. Five seconds is shorter than any change a
+ *  person reading a tooltip could tell apart — neither the five-hour nor the
+ *  weekly window moves measurably in that time — yet long enough that a burst
+ *  of hovers, or several Zeo windows hovered in turn, costs one control request
+ *  between them rather than one each. Much shorter than the idle poll's
+ *  {@link sharedSampleMaxAgeMs}: a hover is someone asking "what is it NOW?",
+ *  and a sample most of an interval old is exactly what the poll already
+ *  showed them. */
+export const USAGE_REFRESH_MAX_SAMPLE_AGE_MS = 5_000;
 /** The SDK's own text for a rejected control request, passed through to the
  *  client as the internal error's message (R2.4). */
 function errorMessage(error) {
@@ -195,6 +217,10 @@ export function parseTasksBackgroundRequest(params) {
         toolCallId: requireIdField(params, TASKS_BACKGROUND_METHOD, "toolCallId"),
     };
 }
+/** Validate raw JSON-RPC params into a {@link UsageRefreshRequest}. */
+export function parseUsageRefreshRequest(params) {
+    return { sessionId: requireIdField(params, USAGE_REFRESH_METHOD, "sessionId") };
+}
 /** How often the account quota windows are refreshed while a session sits idle,
  *  in milliseconds; `0` disables polling entirely.
  *
@@ -204,10 +230,17 @@ export function parseTasksBackgroundRequest(params) {
  *  the old utilization, and the bar is wrong in the one direction that matters
  *  (it under-reports how much is available) until the next turn ends.
  *
+ *  Thirty seconds by default (sixty until the quota tooltip): the tooltip over
+ *  the context ring shows these windows as numbers, so a reading up to a minute
+ *  old was visible as one. The cost does not double with it — every adapter
+ *  process on the desktop shares one sample per interval (quota-cache.ts), so
+ *  it is still about one control request per interval per account. Hovering
+ *  the ring asks for a fresher one on demand (`_claude/usage/refresh`).
+ *
  *  The floor is not timidity: each tick costs one control request, and neither
  *  the five-hour nor the seven-day window can move fast enough for a tighter
  *  loop to show anything a 15-second one would miss. */
-const QUOTA_POLL_DEFAULT_MS = 60_000;
+const QUOTA_POLL_DEFAULT_MS = 30_000;
 const QUOTA_POLL_FLOOR_MS = 15_000;
 /** Whether sessions ask the SDK for progress summaries on subagent tasks
  *  (`CLAUDE_ACP_PROGRESS_SUMMARIES`). Only `1` or `true` turn it on; anything
@@ -251,7 +284,11 @@ export function quotaPollIntervalMs(raw = process.env.CLAUDE_ACP_QUOTA_POLL_MS)
  *  (the result is skipped, its trailing idle absorbed as owed, so the
  *  #825 detector can't fire); misrouting an autonomous result into the
  *  user lane is the bounded misattribution class this set exists to
- *  reduce. */
+ *  reduce.
+ *
+ *  Exception: a result from one of these origins that names a pending prompt
+ *  in `user_message_uuids` consumed that folded prompt and takes the user
+ *  lane (see the result handler). */
 const AUTONOMOUS_RESULT_ORIGINS = new Set([
     "task-notification",
     "peer",
@@ -872,6 +909,7 @@ export class ClaudeAcpAgent {
                         promptQueueing: true,
                     },
                     [TASKS_CAPABILITY_KEY]: { version: TASKS_CAPABILITY_VERSION },
+                    [USAGE_CAPABILITY_KEY]: { version: USAGE_CAPABILITY_VERSION },
                 },
                 promptCapabilities: {
                     image: true,
@@ -1350,14 +1388,19 @@ export class ClaudeAcpAgent {
      */
     /** Fetch the account's quota windows and publish them to this session.
      *
-     *  `allowCache` is the difference between the two callers. A turn ending and a
+     *  `cacheMaxAgeMs` is the difference between the callers. A turn ending and a
      *  session being established are moments when THIS session's own consumption
-     *  just changed, so they always fetch. The idle poll has no such reason: it is
-     *  asking about an account, and every other adapter process on the desktop is
-     *  asking the same question about the same account. It reads the shared sample
-     *  instead -- see quota-cache.ts for why sharing, not tighter intervals, is
-     *  what makes separate windows agree. */
-    async publishAccountUsage(sessionId, session, { allowCache = false } = {}) {
+     *  just changed, so they pass none and always fetch. The idle poll and the
+     *  on-demand refresh have no such reason: they are asking about an account,
+     *  and every other adapter process on the desktop is asking the same question
+     *  about the same account. They accept a shared sample up to that age instead
+     *  -- see quota-cache.ts for why sharing, not tighter intervals, is what makes
+     *  separate windows agree.
+     *
+     *  Resolves `true` when at least one window was published, `false` when none
+     *  was: no report, a report with no plan windows (an API-key session), or a
+     *  session replaced while the request was in flight. Never rejects. */
+    async publishAccountUsage(sessionId, session, { cacheMaxAgeMs } = {}) {
         try {
             // Not `getUsage`: this awful spelling is the only name the real `Query`
             // answers to, and it is written out here rather than hidden behind a
@@ -1371,9 +1414,7 @@ export class ClaudeAcpAgent {
             // A sample another process already paid for, when this call is allowed to
             // take one. `null` covers every failure the cache can have, so a broken
             // cache degrades to exactly the behaviour that existed before it.
-            const cached = allowCache
-                ? await readFreshLimits(sharedSampleMaxAgeMs(quotaPollIntervalMs()))
-                : null;
+            const cached = cacheMaxAgeMs !== undefined ? await readFreshLimits(cacheMaxAgeMs) : null;
             const report = cached ??
                 (await session.query.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET({
                     skipBehaviors: true,
@@ -1388,7 +1429,7 @@ export class ClaudeAcpAgent {
             // flight (provider switch, a changed cwd on session/load). A successor
             // must not inherit its predecessor's windows.
             if (this.sessions[sessionId] !== session) {
-                return;
+                return false;
             }
             // `usage_update` is the only carrier ACP gives this `_meta`, and it
             // requires both numbers. `contextUsedTokens` is the session-scoped mirror
@@ -1404,6 +1445,7 @@ export class ClaudeAcpAgent {
             // single report's bars disagree about the context they were measured in.
             const used = session.contextUsedTokens ?? 0;
             const size = session.contextWindowSize;
+            let published = false;
             for (const window of this.accountUsageTracker(session).windowsFrom(report)) {
                 await this.client.sessionUpdate({
                     sessionId,
@@ -1414,10 +1456,13 @@ export class ClaudeAcpAgent {
                         _meta: { "_claude/rateLimit": window },
                     },
                 });
+                published = true;
             }
+            return published;
         }
         catch (error) {
             this.logger.error(`Session ${sessionId}: structured usage report unavailable: ${error}`);
+            return false;
         }
     }
     /** Start the idle refresh of the account quota windows for this session.
@@ -1438,6 +1483,7 @@ export class ClaudeAcpAgent {
         if (intervalMs === 0) {
             return;
         }
+        const cacheMaxAgeMs = sharedSampleMaxAgeMs(intervalMs);
         // Closure-local rather than a Session field: it guards this timer alone, and
         // a slow report must not let ticks pile up into a queue of duplicate control
         // requests against a session that is already struggling to answer one.
@@ -1456,7 +1502,7 @@ export class ClaudeAcpAgent {
             inFlight = true;
             // `publishAccountUsage` never rejects — it logs and returns — so this
             // cannot become an unhandled rejection, and `finally` always re-opens.
-            void this.publishAccountUsage(sessionId, session, { allowCache: true }).finally(() => {
+            void this.publishAccountUsage(sessionId, session, { cacheMaxAgeMs }).finally(() => {
                 inFlight = false;
             });
         }, intervalMs);
@@ -1464,6 +1510,70 @@ export class ClaudeAcpAgent {
         timer.unref?.();
         session.accountUsageTimer = timer;
     }
+    /**
+     * `_claude/usage/refresh`: publish this session's quota windows now, on
+     * demand, and answer whether any were published.
+     *
+     * The client asks on every hover of the context ring, so the cost is bounded
+     * twice. A shared sample younger than {@link USAGE_REFRESH_MAX_SAMPLE_AGE_MS}
+     * answers without a control request, and a refresh already in flight for this
+     * session is joined rather than repeated — however fast the hovers come, one
+     * session never has two of these requests queued.
+     *
+     * Skipped while a turn is in flight, answering `{ refreshed: false }`. The
+     * report is read-only, but SDK control requests are SERIALIZED: an interrupt
+     * queued behind a usage request waits for it (upstream #1216 measured
+     * 0.7-1.1 s for the same queueing behind `getContextUsage`), and `cancel`
+     * awaits its interrupt. A hover during a turn is the common case — people
+     * watch the ring fill — so allowing it would put a round-trip in front of the
+     * Stop button exactly when it is most likely to be pressed. Nothing is lost:
+     * the turn's own end refreshes the windows (R1.2), and a live
+     * `rate_limit_event` still lands mid-turn.
+     *
+     * Before the first turn a control request may not be serviced at all on older
+     * CLIs (#886/#880); such a call simply waits, joined by every later hover,
+     * alongside the establishment refresh that is already waiting the same way.
+     *
+     * Never rejects for a missing report: a fetch failure is logged by
+     * `publishAccountUsage` and answers `false`, as does an API-key session,
+     * which has no plan windows to publish. Only an unknown session is an error,
+     * the same invalid-params error the `_claude/tasks` methods answer.
+     */
+    async refreshUsage(params) {
+        const { sessionId } = params;
+        const log = (outcome, reason) => this.logger.log(`[usage/refresh] method=${USAGE_REFRESH_METHOD} sessionId=${logValue(sessionId)} outcome=${outcome}` +
+            (reason ? ` reason=${reason}` : ""));
+        const session = Object.hasOwn(this.sessions, sessionId) ? this.sessions[sessionId] : undefined;
+        if (!session) {
+            log("error", "unknown_session");
+            throw RequestError.invalidParams(undefined, `unknown session ${sessionId}`);
+        }
+        if (session.queryClosed) {
+            log("skipped", "session_ended");
+            return { refreshed: false };
+        }
+        let coalesced = true;
+        let pending = session.usageRefreshInFlight;
+        if (!pending) {
+            if (session.turnQueue?.length || session.activeTurn) {
+                log("skipped", "turn_in_flight");
+                return { refreshed: false };
+            }
+            coalesced = false;
+            pending = this.publishAccountUsage(sessionId, session, {
+                cacheMaxAgeMs: USAGE_REFRESH_MAX_SAMPLE_AGE_MS,
+            }).finally(() => {
+                if (session.usageRefreshInFlight === pending) {
+                    session.usageRefreshInFlight = undefined;
+                }
+            });
+            session.usageRefreshInFlight = pending;
+        }
+        // `publishAccountUsage` never rejects, so neither does this await.
+        const refreshed = await pending;
+        log(refreshed ? "published" : "nothing", coalesced ? "coalesced" : undefined);
+        return { refreshed };
+    }
     async publishGoalFromPrompt(sessionId, prompt, commandUuid) {
         const goalUpdate = goalUpdateFromPrompt(prompt);
         if (goalUpdate !== undefined) {
@@ -2115,6 +2225,40 @@ export class ClaudeAcpAgent {
         };
         /** The unsettled in-flight turn owning this prompt uuid, if any. */
         const findUnsettledTurn = (uuid) => (session.turnQueue ?? []).find((t) => t.promptUuid === uuid && !t.settled);
+        /** Whether this result is the answer to a prompt that is still waiting.
+         *
+         *  Claude Code can start a turn on its own, for example when a background
+         *  task finishes. If the user sends a prompt while that turn runs, Claude
+         *  Code adds the prompt to the running turn. The turn's result is still
+         *  marked as a background result, but it lists the uuids of the prompts it
+         *  answered.
+         *
+         *  A turn held open for its background subagents already has its result,
+         *  so a result that names it does not answer it. */
+        const answersPendingPrompt = (message) => {
+            // Newer CLIs list every prompt the turn answered. Older ones name only
+            // the last one.
+            let answeredPromptUuids = [];
+            if (Array.isArray(message.user_message_uuids)) {
+                answeredPromptUuids = message.user_message_uuids;
+            }
+            else if (typeof message.user_message_uuid === "string") {
+                answeredPromptUuids = [message.user_message_uuid];
+            }
+            for (const promptUuid of answeredPromptUuids) {
+                const turn = findUnsettledTurn(promptUuid);
+                if (turn === undefined) {
+                    // Not a prompt of this session, or it was answered already.
+                    continue;
+                }
+                if (isHeldOpen(turn)) {
+                    // This turn already has its result and only waits for its subagents.
+                    continue;
+                }
+                return true;
+            }
+            return false;
+        };
         /** The first queued turn still awaiting its outcome, if any — the single
          *  spelling of "a prompt is pending" shared by the head promotion and
          *  the autonomous stretch-close guard. */
@@ -3403,7 +3547,10 @@ export class ClaudeAcpAgent {
                         // the user's prompt's. Autonomous results must never touch the
                         // user-turn lifecycle (stop reason, settles, failActive,
                         // slash-command output forwarding), though their cost is real.
-                        const isAutonomousResult = message.origin != null && AUTONOMOUS_RESULT_ORIGINS.has(message.origin.kind);
+                        // The exception: the user's prompt was added to that turn while it
+                        // ran, so its result answers the prompt (see answersPendingPrompt).
+                        const startedByClaudeCode = message.origin != null && AUTONOMOUS_RESULT_ORIGINS.has(message.origin.kind);
+                        const isAutonomousResult = startedByClaudeCode && !answersPendingPrompt(message);
                         const pendingExitPlanModeInterruption = session.pendingExitPlanModeInterruption;
                         const pendingExitPlanContextReset = session.pendingExitPlanContextReset;
                         try {
@@ -4962,6 +5109,18 @@ export class ClaudeAcpAgent {
             await this.applyFastMode(session, resolveFastModeEnabled(params));
             return { configOptions: session.configOptions };
         }
+        // Ultracode is a boolean too, and bypasses the same validation. The legacy
+        // `effort = "ultracode"` (the retired notch) is accepted for one release.
+        const useBoolean = clientSupportsBooleanConfigOptions(this.clientCapabilities);
+        if (params.configId === ULTRACODE_CONFIG_ID) {
+            await applyUltracodeToggle(session, resolveUltracodeRequested(params), useBoolean);
+            return { configOptions: session.configOptions };
+        }
+        if (params.configId === EFFORT_CONFIG_ID &&
+            isLegacyUltracodeEffort(params.value) &&
+            (await applyLegacyUltracodeEffort(session, useBoolean))) {
+            return { configOptions: session.configOptions };
+        }
         // The Thinking toggle only records the session's intent — the SDK query
         // swap is deferred to the next prompt() start (lazy recreate, sub-task
         // 1.3), so there is no SDK call to fail here and the config option is
@@ -5647,7 +5806,10 @@ export class ClaudeAcpAgent {
             if (session.fastModeDisabledReason === "model_not_allowed") {
                 session.fastModeDisabledReason = undefined;
             }
-            // Rebuild config options since effort levels depend on the selected model
+            // Rebuild config options since effort levels depend on the selected model.
+            // The new model decides whether Ultracode is shown (heuristic now, the
+            // CLI's readback below); the retained intent decides its value.
+            session.ultracodeAvailable = isUltracodeAvailable(newModelInfo?.supportsEffort ? (newModelInfo.supportedEffortLevels ?? []) : [], { disableWorkflows: session.workflowsDisabled });
             const effortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
             const currentEffort = typeof effortOpt?.currentValue === "string" ? effortOpt.currentValue : undefined;
             session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, currentEffort, session.agents, session.currentAgent, {
@@ -5666,15 +5828,7 @@ export class ClaudeAcpAgent {
             // (R1.6).
             session.thinkingEnabled ??
                 effectiveThinkingConfig(undefined, process.env.MAX_THINKING_TOKENS, this.logger) !==
-                    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,
+                    undefined, this.ultracodeState(session, session.ultracodeAvailable), {
                 // 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
@@ -5686,8 +5840,7 @@ export class ClaudeAcpAgent {
             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(ultracodeFlagSettings(newEffort));
-                session.ultracode = isUltracodeValue(newEffort);
+                await session.query.applyFlagSettings(effortFlagSettings(newEffort, session.ultracodeRequested));
             }
             // Emit current_mode_update only after session.modes AND
             // session.configOptions have been fully reconciled. This way, a failure
@@ -5699,8 +5852,10 @@ export class ClaudeAcpAgent {
                 await this.sessionModes.publishFallbackState(sessionId, session);
             }
             // Last, so the switch's own control requests don't queue behind it.
-            if (modelChanged)
+            if (modelChanged) {
                 this.refreshContextWindowInBackground(sessionId, session);
+                this.refreshUltracodeInBackground(sessionId, session, false);
+            }
         }
         else if (configId === AGENT_CONFIG_ID) {
             // Live agent switch — no subprocess restart needed. Apply the SDK flag
@@ -5737,11 +5892,9 @@ export class ClaudeAcpAgent {
         else {
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
             if (configId === EFFORT_CONFIG_ID) {
-                // 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);
+                // An effort change without `ultracode` turns it off, so the intent
+                // rides along — see `effortFlagSettings`.
+                await session.query.applyFlagSettings(effortFlagSettings(value, session.ultracodeRequested));
             }
         }
     }
@@ -5794,6 +5947,50 @@ export class ClaudeAcpAgent {
         session.fastModeEnabled = enabled;
         this.refreshFastModeOption(session, enabled);
     }
+    /** The Ultracode display state for `buildConfigOptions`. */
+    ultracodeState(session, available) {
+        return {
+            available,
+            requested: session.ultracodeRequested,
+            useBooleanOption: clientSupportsBooleanConfigOptions(this.clientCapabilities),
+        };
+    }
+    /**
+     * Replace the Ultracode heuristic with the CLI's `applied` report, without
+     * blocking the caller — never inline, because control requests queue ahead
+     * of interrupt and close (upstream #1216). `seedIntent` at session start; a
+     * model switch keeps its intent and only re-reads availability. Deferred a
+     * tick so a resulting `config_option_update` follows the session/new reply.
+     */
+    refreshUltracodeInBackground(sessionId, session, seedIntent) {
+        const { query } = session;
+        const modelId = session.models.currentModelId;
+        const requestedAtStart = session.ultracodeRequested;
+        const stillCurrent = () => this.sessions[sessionId] === session &&
+            session.query === query &&
+            session.models.currentModelId === modelId;
+        setTimeout(() => {
+            void readUltracodeState(query, (error) => {
+                this.logger.log(`[ultracode] get_settings failed session=${sessionId}: ${String(error)}`);
+            })
+                .then(async (readback) => {
+                if (!readback || !stillCurrent())
+                    return;
+                // A toggle that landed while the read was in flight is newer than it.
+                const seed = seedIntent && session.ultracodeRequested === requestedAtStart;
+                const useBoolean = clientSupportsBooleanConfigOptions(this.clientCapabilities);
+                if (!applyUltracodeReadback(session, readback, seed, useBoolean))
+                    return;
+                await this.client.sessionUpdate({
+                    sessionId,
+                    update: { sessionUpdate: "config_option_update", configOptions: session.configOptions },
+                });
+            })
+                .catch((error) => {
+                this.logger.error(`[ultracode] readback failed session=${sessionId}:`, error);
+            });
+        }, 0);
+    }
     /** Lazily swap a session's SDK query for a fresh one so a Thinking change
      *  takes effect on the next turn (R1.3): thinking has no live flag-settings
      *  path in the SDK, so mid-session application goes through query recreation
@@ -5915,14 +6112,16 @@ export class ClaudeAcpAgent {
                 // await is already included.
                 const effortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
                 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
+                const effortFlags = effortFlagSettings(effortValue, session.ultracodeRequested);
+                // Only the positive cases are 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(ultracode === true ? { effortLevel, ultracode: true } : { effortLevel });
+                // request that says nothing. The Ultracode intent is replayed even at
+                // Default effort.
+                if (effortFlags.effortLevel !== null) {
+                    await replacement.applyFlagSettings(effortFlags);
+                }
+                else if (effortFlags.ultracode) {
+                    await replacement.applyFlagSettings({ ultracode: true });
                 }
                 const supportsFastMode = session.modelInfos.find((m) => m.value === session.models.currentModelId)
                     ?.supportsFastMode ?? false;
@@ -6704,6 +6903,7 @@ export class ClaudeAcpAgent {
             disabledReason: fastModeDisabledReason,
         };
         const workflowsDisabled = settingsManager.getSettings().disableWorkflows === true;
+        const ultracodeRequested = settingsManager.getSettings().ultracode === true;
         const configOptions = buildConfigOptions(modes, models, 
         // Catalog-based (see `modelInfos` above), matching the model-switch
         // rebuild (which passes `session.modelInfos`): `buildConfigOptions`
@@ -6717,31 +6917,24 @@ 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, {
-            // 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,
+        thinking !== undefined, 
+        // Seeded from settings and the heuristic; the CLI's own report replaces
+        // both in the background (`refreshUltracodeInBackground`, below).
+        this.ultracodeState({ ultracodeRequested }, isUltracodeAvailable(currentModelInfo?.supportsEffort ? (currentModelInfo.supportedEffortLevels ?? []) : [], { 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
+        // Apply the initial effort level to the SDK so it matches the UI default.
+        // It carries the Ultracode intent: an effort change without the key would
+        // turn off an `ultracode: true` the session was started with.
         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(ultracodeFlagSettings(initialEffort.currentValue));
+            await q.applyFlagSettings(effortFlagSettings(initialEffort.currentValue, ultracodeRequested));
         }
         // Seed the context window WITHOUT any extra IPC on the session/new path.
         // On session/load, the resumed session's own `getContextUsage` report — a
@@ -6806,7 +6999,8 @@ export class ClaudeAcpAgent {
             configOptions,
             agents,
             currentAgent,
-            ultracode: initialUltracode,
+            ultracodeRequested,
+            ultracodeAvailable: configOptions.some((o) => o.id === ULTRACODE_CONFIG_ID),
             workflowsDisabled,
             declaredAccounts,
             currentAccount: accountEntry?.value,
@@ -6854,6 +7048,7 @@ export class ClaudeAcpAgent {
         // A guessed window seed (text heuristic / default) is refined the same way,
         // unawaited; a resumed session's authoritative seed makes it a no-op.
         this.refreshContextWindowInBackground(sessionId, this.sessions[sessionId]);
+        this.refreshUltracodeInBackground(sessionId, this.sessions[sessionId], true);
         return {
             sessionId,
             modes,
@@ -7187,16 +7382,11 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
  *  Both session call sites always supply it (R1.1); `undefined` (direct
  *  callers/tests) omits the row. */
 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. */
+/** Display state for the Ultracode option, placed after effort. Omitted by
+ *  direct callers/tests, in which case the option is not shown. */
 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. */
+/** The declared accounts plus the one in force, which decide whether an
+ *  account selector is advertised at all (R6.1/R6.2). */
 settings) {
     const options = [
         SessionModeManager.configOption(modes),
@@ -7230,11 +7420,6 @@ settings) {
         ? (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) => ({
@@ -7244,21 +7429,9 @@ settings) {
                     .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) ||
-            (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";
+        const includes = (l) => l === "default" || supportedLevels.includes(l);
+        const validEffort = currentEffortLevel && includes(currentEffortLevel) ? currentEffortLevel : "default";
         options.push({
             id: EFFORT_CONFIG_ID,
             name: "Effort",
@@ -7269,6 +7442,11 @@ settings) {
             options: effortOptions,
         });
     }
+    // Ultracode: a toggle beside effort, not an effort level (`ultracode.ts`).
+    const ultracodeOption = ultracodeConfigOption(ultracode);
+    if (ultracodeOption) {
+        options.push(ultracodeOption);
+    }
     // Surface the Fast mode toggle only when the current model supports it. The
     // option renders as a native boolean toggle for Clients that opted in, and a
     // two-value select otherwise.
@@ -8724,6 +8902,7 @@ export function runAcp(logger) {
         .onRequest(TASKS_STOP_METHOD, { parse: parseTasksStopRequest }, (ctx) => agent.stopTask(ctx.params))
         .onRequest(TASKS_OUTPUT_METHOD, { parse: parseTasksOutputRequest }, (ctx) => agent.taskOutput(ctx.params))
         .onRequest(TASKS_BACKGROUND_METHOD, { parse: parseTasksBackgroundRequest }, (ctx) => agent.backgroundTask(ctx.params))
+        .onRequest(USAGE_REFRESH_METHOD, { parse: parseUsageRefreshRequest }, (ctx) => agent.refreshUsage(ctx.params))
         .onRequest(GOAL_CONTROL_METHOD, { parse: parseGoalRequest }, (ctx) => agent.goal(ctx.params))
         .connect(stream);
     agent = new ClaudeAcpAgent(new ClientConnection(connection.client), logger);