@lucascouts/claude-agent-acp-plus 0.27.0 → 0.29.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";
@@ -174,6 +174,14 @@ export const USAGE_CAPABILITY_VERSION = 1;
  *  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;
+/** Parity item 106 (upstream issue #1284): how long a turn held for its
+ *  background subagents (see `Turn.deferredSettle`) waits, once none of them is
+ *  live and Claude Code is idle, for the followup cycle a task_notification
+ *  would start. A notification that is lost starts none, and with no further
+ *  idle nothing else would ever answer the prompt. A followup starts within
+ *  milliseconds of its notification (the CLI flushes them together), so the
+ *  bound only ever expires on a lost one. */
+export const HELD_TURN_DRAIN_GRACE_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) {
@@ -284,7 +292,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",
@@ -2221,6 +2233,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. */
@@ -2291,6 +2337,34 @@ export class ClaudeAcpAgent {
          *  while true, the turn's settlement stays deferred so the subagent's
          *  output and permission requests land inside it (see
          *  Turn.deferredSettle). */
+        /** Ends the display terminal of a command that went to the background,
+         *  once its task ends (see `Session.backgroundTerminals`). The code is the
+         *  one Claude Code's summary names, else 1 for a failed or stopped task —
+         *  a known failure never goes out as null — and null for a completion
+         *  that names none. */
+        const endBackgroundTerminal = async (taskId, exitCode) => {
+            const terminal = session.backgroundTerminals?.get(taskId);
+            if (!terminal)
+                return;
+            session.backgroundTerminals.delete(taskId);
+            await sendUpdate({
+                sessionId: params.sessionId,
+                update: {
+                    sessionUpdate: "tool_call_update",
+                    toolCallId: terminal.toolCallId,
+                    _meta: {
+                        ...(terminal.parentToolUseId
+                            ? { claudeCode: { parentToolUseId: terminal.parentToolUseId } }
+                            : {}),
+                        terminal_exit: {
+                            terminal_id: terminal.toolCallId,
+                            exit_code: exitCode,
+                            signal: null,
+                        },
+                    },
+                },
+            });
+        };
         const turnAwaitingSubagents = (turn) => {
             if (!turn.spawnedTaskIds?.size) {
                 return false;
@@ -2318,6 +2392,33 @@ export class ClaudeAcpAgent {
                 settleActive(turn.deferredSettle);
             }
         };
+        /** Item 106: arms the drain grace (see `HELD_TURN_DRAIN_GRACE_MS`) when a
+         *  prune leaves the held turn with no live subagent while Claude Code is
+         *  idle — the state in which a lost task_notification parks the turn. At
+         *  expiry the turn settles only if nothing moved: same turn, still held,
+         *  still drained, still idle. A followup that started meanwhile (state
+         *  `running`) settles the turn itself at its result or idle. */
+        let drainGrace;
+        const armDrainGrace = () => {
+            const turn = session.activeTurn;
+            if (drainGrace !== undefined ||
+                !isHeldOpen(turn) ||
+                turnAwaitingSubagents(turn) ||
+                session.lastSessionState !== "idle") {
+                return;
+            }
+            drainGrace = setTimeout(() => {
+                drainGrace = undefined;
+                if (session.activeTurn === turn &&
+                    isHeldOpen(turn) &&
+                    !turnAwaitingSubagents(turn) &&
+                    session.lastSessionState === "idle") {
+                    this.logger.log(`[held-turn] settled after the drain grace: no followup came (task_notification lost?) session=${params.sessionId}`);
+                    settleDeferredIfDrained();
+                }
+            }, HELD_TURN_DRAIN_GRACE_MS);
+            drainGrace.unref?.();
+        };
         /** Settle the active turn with `outcome` now — unless subagents it
          *  spawned are still live, in which case store the outcome and hold the
          *  turn open (see Turn.deferredSettle). Every result-time settle of a
@@ -3270,6 +3371,8 @@ export class ClaudeAcpAgent {
                                 // The task settled — no further tool calls can originate
                                 // from it, so its registry entry can be dropped.
                                 session.liveBackgroundTasks.delete(message.task_id);
+                                await endBackgroundTerminal(message.task_id, backgroundExitCode(message.status, message.summary));
+                                armDrainGrace();
                                 if (session.taskFeed && session.taskFeedPublisher) {
                                     const readable = await endingOutputReadable(session, message.task_id, message.output_file);
                                     const change = session.taskFeed.onNotification(message);
@@ -3289,6 +3392,10 @@ export class ClaudeAcpAgent {
                                     message.patch.status === "failed" ||
                                     message.patch.status === "killed") {
                                     session.liveBackgroundTasks.delete(message.task_id);
+                                    // Usually first: the notification with its summary follows
+                                    // but is not guaranteed, so the terminal ends here.
+                                    await endBackgroundTerminal(message.task_id, backgroundExitCode(message.patch.status, message.patch.error));
+                                    armDrainGrace();
                                 }
                                 if (session.taskFeed && session.taskFeedPublisher) {
                                     // The CLI queues the terminal patch BEFORE the
@@ -3488,6 +3595,7 @@ export class ClaudeAcpAgent {
                                             session.liveBackgroundTasks.delete(taskId);
                                         }
                                     }
+                                    armDrainGrace();
                                 }
                                 // The same level, forwarded: once the turn has settled the
                                 // client reads the thread as idle, and a background shell or
@@ -3509,7 +3617,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 {
@@ -4427,6 +4538,19 @@ export class ClaudeAcpAgent {
                         // Before toAcpNotifications, which prunes the tool_use cache entry
                         // that says the result is a Bash call's.
                         observeBackgroundBashResult(message, content, session);
+                        // The command's terminal runs until its task ends, unless the task
+                        // has ended already (a fast command can end before its result).
+                        const runningTerminal = this.clientCapabilities?._meta?.["terminal_output"] === true
+                            ? backgroundBashTerminal(message, content, session)
+                            : undefined;
+                        if (runningTerminal && session.liveBackgroundTasks.has(runningTerminal.taskId)) {
+                            (session.backgroundTerminals ??= new Map()).set(runningTerminal.taskId, {
+                                toolCallId: runningTerminal.toolCallId,
+                                ...(message.parent_tool_use_id
+                                    ? { parentToolUseId: message.parent_tool_use_id }
+                                    : {}),
+                            });
+                        }
                         for (const notification of toAcpNotifications(content, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
                             clientCapabilities: this.clientCapabilities,
                             parentToolUseId: message.parent_tool_use_id,
@@ -4454,7 +4578,9 @@ export class ClaudeAcpAgent {
                             // filtered out of `content` above; blocks that do pass through
                             // (e.g. a subagent image) carry the stamped parentToolUseId
                             // meta and are excluded there.
-                            await sendUpdate(acceptedPlanToolResult(notification, acceptedPlanToolUseId));
+                            await sendUpdate(withRunningTerminal(acceptedPlanToolResult(notification, acceptedPlanToolUseId), runningTerminal && session.backgroundTerminals?.has(runningTerminal.taskId)
+                                ? runningTerminal.toolCallId
+                                : undefined));
                         }
                         break;
                     }
@@ -5068,6 +5194,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
@@ -5696,6 +5834,13 @@ export class ClaudeAcpAgent {
      * Not written to `contextWindowCache` — that stays keyed to the
      * `result.modelUsage` spellings — and a result still overwrites it.
      * Ported from upstream #1186.
+     *
+     * Asks for the `summary` detail (parity item 97, upstream #1258): the
+     * default `full` breakdown issues one `messages/count_tokens` call per
+     * category, and only `rawMaxTokens` is read here. The two other callers
+     * (`readResumedLiveModel`, `fetchContextUsedTokens`) read `totalTokens`,
+     * which `summary` takes from the last response's usage plus local
+     * estimates instead of counting — not the same number, so they keep `full`.
      */
     refreshContextWindowInBackground(sessionId, session) {
         if (session.contextWindowAuthoritative)
@@ -5707,7 +5852,7 @@ export class ClaudeAcpAgent {
             session.models.currentModelId === modelId;
         // A synchronous throw must not fail the caller either.
         Promise.resolve()
-            .then(() => query.getContextUsage())
+            .then(() => query.getContextUsage({ detail: "summary" }))
             .then((usage) => {
             if (!stillCurrent() || session.contextWindowAuthoritative)
                 return;
@@ -5753,7 +5898,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, {
@@ -5772,15 +5920,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
@@ -5792,8 +5932,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
@@ -5805,8 +5944,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
@@ -5843,11 +5984,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));
             }
         }
     }
@@ -5900,6 +6039,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
@@ -6021,14 +6204,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;
@@ -6810,6 +6995,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`
@@ -6823,31 +7009,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
@@ -6912,7 +7091,8 @@ export class ClaudeAcpAgent {
             configOptions,
             agents,
             currentAgent,
-            ultracode: initialUltracode,
+            ultracodeRequested,
+            ultracodeAvailable: configOptions.some((o) => o.id === ULTRACODE_CONFIG_ID),
             workflowsDisabled,
             declaredAccounts,
             currentAccount: accountEntry?.value,
@@ -6960,6 +7140,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,
@@ -7293,16 +7474,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),
@@ -7336,11 +7512,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) => ({
@@ -7350,21 +7521,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",
@@ -7375,6 +7534,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.
@@ -9005,6 +9169,71 @@ function getMatchingModelUsage(modelUsage, currentModel) {
         return { key: bestKey, usage: modelUsage[bestKey] };
     }
 }
+/**
+ * Parity item 92: the Bash tool call and task of a command this result sent to
+ * the background — the structured `BashOutput` carries `backgroundTaskId`, and
+ * the message holds exactly one tool_result, of a Bash call.
+ */
+function backgroundBashTerminal(message, content, session) {
+    if (message.type !== "user" || !Array.isArray(content))
+        return undefined;
+    const result = message.tool_use_result;
+    if (typeof result !== "object" || result === null || !("backgroundTaskId" in result)) {
+        return undefined;
+    }
+    const taskId = result.backgroundTaskId;
+    if (typeof taskId !== "string" || taskId === "")
+        return undefined;
+    const blocks = content.filter((c) => typeof c === "object" && c !== null && c.type === "tool_result");
+    if (blocks.length !== 1)
+        return undefined;
+    const toolCallId = blocks[0].tool_use_id;
+    if (session.toolUseCache[toolCallId]?.name !== "Bash")
+        return undefined;
+    return { taskId, toolCallId };
+}
+/**
+ * Drops `terminal_exit` from the tool result update of `toolCallId`: the Bash
+ * call returned as soon as its command detached, and the exit would mark the
+ * terminal as ended while the command still runs.
+ */
+export function withRunningTerminal(notification, toolCallId) {
+    const update = notification.update;
+    if (toolCallId === undefined ||
+        update.sessionUpdate !== "tool_call_update" ||
+        update.toolCallId !== toolCallId ||
+        !update._meta ||
+        !("terminal_exit" in update._meta)) {
+        return notification;
+    }
+    const meta = { ...update._meta };
+    delete meta.terminal_exit;
+    const next = { ...update, _meta: meta };
+    if (Object.keys(meta).length === 0)
+        delete next._meta;
+    return { ...notification, update: next };
+}
+/**
+ * The exit code of a background command whose task ended, from what the task's
+ * ending says. Claude Code's summary reads `Background command "<d>" completed
+ * (exit code N[: note])` or `… failed with exit code N` (CLI 2.1.285); an
+ * ending names a code only at its end, so a description holding the words
+ * cannot be mistaken for it. A completion with a non-zero code is one Claude
+ * Code accepted as a success (grep's "No matches found"), so it goes out as
+ * null; a failure or stop that names no code goes out as 1, never null.
+ */
+export function backgroundExitCode(status, text) {
+    const failed = status === "failed" || status === "killed" || status === "stopped";
+    const said = typeof text === "string" ? text : "";
+    if (failed) {
+        const match = /exit code (\d+)\s*$/.exec(said);
+        return match ? Number(match[1]) : 1;
+    }
+    const match = /\(exit code (\d+)(?::[^)]*)?\)\s*$/.exec(said);
+    if (match && Number(match[1]) === 0)
+        return 0;
+    return null;
+}
 /**
  * Story 041 (R1.1, R1.6): a backgrounded Bash call's result names the file the
  * CLI writes its output to. When the structured `BashOutput` carries

package/dist/tools.d.ts

@@ -23,7 +23,8 @@ interface ToolUpdate {
         };
         terminal_exit?: {
             terminal_id: string;
-            exit_code: number;
+            /** Null when the code is not known (as in `TerminalExitStatus`). */
+            exit_code: number | null;
             signal: string | null;
         };
     };
@@ -40,6 +41,12 @@ export type ClaudePlanEntry = {
     status: "pending" | "in_progress" | "completed";
     activeForm: string;
 };
+/**
+ * The exit code the text of a failed command names. Claude Code starts the text
+ * of a command that exited with a failing code with `Exit code N`; other
+ * failures, such as a denial or a command that could not start, name none.
+ */
+export declare function failureExitCode(text: string): number | undefined;
 export declare function planEntries(input: {
     todos: ClaudePlanEntry[];
 } | undefined): PlanEntry[];

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}