@cloudcli-ai/cloudcli 1.37.2 → 1.37.3

package/server/modules/projects/services/project-star.service.ts

@@ -40,7 +40,7 @@ export function applyLegacyStarredProjectIds(projectIds: string[]): ApplyLegacyS
       continue;
     }
 
-    if (Boolean(project.isStarred)) {
+    if (project.isStarred) {
       continue;
     }
 
@@ -71,7 +71,7 @@ export function toggleProjectStar(projectId: string): ToggleProjectStarResult {
     });
   }
 
-  const nextStarredState = !Boolean(project.isStarred);
+  const nextStarredState = !project.isStarred;
   projectsDb.updateProjectIsStarredById(normalizedProjectId, nextStarredState);
 
   return { isStarred: nextStarredState };

package/server/modules/providers/index.ts

@@ -6,5 +6,9 @@ export { providerRuntimeService } from './services/provider-runtime.service.js';
 // providerModelsService: used by Commands to list models and resolve the active session model.
 export { providerModelsService } from './services/provider-models.service.js';
 
+// sessionsService: used by the websocket module's chat gateway to resolve an
+// edited message's resume point, which only the providers module can read.
+export { sessionsService } from './services/sessions.service.js';
+
 export { initializeSessionsWatcher } from './services/sessions-watcher.service.js';
 export { closeSessionsWatcher } from './services/sessions-watcher.service.js';

package/server/modules/providers/list/claude/claude-auth.provider.ts

@@ -25,7 +25,9 @@ export class ClaudeProviderAuth implements IProviderAuth {
    * Checks whether the Claude Code CLI is available on this host.
    */
   private checkInstalled(): boolean {
-    const cliPath = resolveClaudeCodeExecutablePath(process.env.CLAUDE_CLI_PATH);
+    // cross-spawn resolves shims and PATHEXT itself, so the bare command is a
+    // usable fallback here even where the SDK's raw spawn could not use it.
+    const cliPath = resolveClaudeCodeExecutablePath(process.env.CLAUDE_CLI_PATH) ?? 'claude';
     try {
       spawn.sync(cliPath, ['--version'], { stdio: 'ignore', timeout: 5000 });
       return true;
@@ -126,6 +128,24 @@ export class ClaudeProviderAuth implements IProviderAuth {
           };
         }
 
+        // `accessToken` is short-lived (hours). Claude Code renews it silently
+        // from `refreshToken` on the next CLI invocation, so an expired access
+        // token alongside a live refresh token is still a working login. Before
+        // this check, a still-signed-in account read as "login has expired"
+        // until something else happened to run the CLI — which is why opening
+        // the Shell tab and coming back made Settings flip to Connected.
+        const refreshToken = readOptionalString(oauth?.refreshToken);
+        const refreshTokenExpiresAt = typeof oauth?.refreshTokenExpiresAt === 'number'
+          ? oauth.refreshTokenExpiresAt
+          : undefined;
+        if (refreshToken && (!refreshTokenExpiresAt || Date.now() < refreshTokenExpiresAt)) {
+          return {
+            authenticated: true,
+            email,
+            method: 'credentials_file',
+          };
+        }
+
         return {
           authenticated: false,
           email: null,

package/server/modules/providers/list/claude/claude-fork.provider.ts

@@ -0,0 +1,57 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { forkSession as forkClaudeSession } from '@anthropic-ai/claude-agent-sdk';
+
+import type { IProviderFork } from '@/shared/interfaces.js';
+import { AppError } from '@/shared/utils.js';
+
+/**
+ * Branches a Claude conversation by copying its transcript into a new session
+ * file.
+ *
+ * The SDK owns this: it remaps every message uuid and rewrites the parentUuid
+ * chain, which is what makes the copy resumable rather than just a duplicate
+ * file. `upToMessageId` is inclusive of the row it names.
+ */
+export class ClaudeForkProvider implements IProviderFork {
+  async forkSession(input: {
+    providerSessionId: string;
+    jsonlPath: string;
+    projectPath: string;
+    upToAnchorId?: string;
+    title?: string;
+  }): Promise<{ providerSessionId: string; jsonlPath: string }> {
+    // `dir` is the session's working directory, which the SDK encodes into the
+    // `~/.claude/projects/<encoded>` folder name itself — passing that folder
+    // makes it encode an already-encoded path and find nothing.
+    const { sessionId } = await forkClaudeSession(input.providerSessionId, {
+      dir: input.projectPath,
+      upToMessageId: input.upToAnchorId,
+      title: input.title,
+    });
+
+    if (!sessionId) {
+      throw new AppError('Claude did not return a session id for the fork.', {
+        code: 'FORK_FAILED',
+        statusCode: 502,
+      });
+    }
+
+    // Confirmed rather than assumed: the caller is about to write a database
+    // row claiming this file exists, and a half-created row would show up in
+    // the sidebar as a session that can never be opened.
+    // The fork lands beside the transcript it was copied from.
+    const forkedPath = path.join(path.dirname(input.jsonlPath), `${sessionId}.jsonl`);
+    try {
+      await stat(forkedPath);
+    } catch {
+      throw new AppError('Claude reported a fork but wrote no transcript for it.', {
+        code: 'FORK_FAILED',
+        statusCode: 502,
+      });
+    }
+
+    return { providerSessionId: sessionId, jsonlPath: forkedPath };
+  }
+}

package/server/modules/providers/list/claude/claude-models.provider.ts

@@ -9,6 +9,19 @@ import type {
 } from '@/shared/types.js';
 import { buildDefaultProviderCurrentActiveModel } from '@/shared/utils.js';
 
+/**
+ * Ultracode is not one of the SDK's reasoning-effort levels. Selecting it runs the turn at
+ * `xhigh` effort with standing dynamic-workflow orchestration, which the Claude runtime
+ * translates into the session-scoped `ultracode` setting. It is therefore only offered on
+ * models this catalog already marks as xhigh-capable.
+ */
+export const CLAUDE_ULTRACODE_EFFORT = 'ultracode';
+
+const ULTRACODE_EFFORT_OPTION = {
+  value: CLAUDE_ULTRACODE_EFFORT,
+  description: 'Highest effort plus standing workflow orchestration.',
+};
+
 export const CLAUDE_PREDEFINED_MODELS: ProviderModelsDefinition = {
   OPTIONS: [
     {
@@ -37,6 +50,7 @@ export const CLAUDE_PREDEFINED_MODELS: ProviderModelsDefinition = {
           { value: 'high' },
           { value: 'xhigh' },
           { value: 'max' },
+          ULTRACODE_EFFORT_OPTION,
         ],
       },
     },
@@ -52,6 +66,7 @@ export const CLAUDE_PREDEFINED_MODELS: ProviderModelsDefinition = {
           { value: 'high' },
           { value: 'xhigh' },
           { value: 'max' },
+          ULTRACODE_EFFORT_OPTION,
         ],
       },
     },
@@ -67,6 +82,7 @@ export const CLAUDE_PREDEFINED_MODELS: ProviderModelsDefinition = {
           { value: 'high' },
           { value: 'xhigh' },
           { value: 'max' },
+          ULTRACODE_EFFORT_OPTION,
         ],
       },
     },
@@ -82,6 +98,7 @@ export const CLAUDE_PREDEFINED_MODELS: ProviderModelsDefinition = {
           { value: 'high' },
           { value: 'xhigh' },
           { value: 'max' },
+          ULTRACODE_EFFORT_OPTION,
         ],
       },
     },
@@ -97,6 +114,7 @@ export const CLAUDE_PREDEFINED_MODELS: ProviderModelsDefinition = {
           { value: 'high' },
           { value: 'xhigh' },
           { value: 'max' },
+          ULTRACODE_EFFORT_OPTION,
         ],
       },
     },
@@ -112,6 +130,7 @@ export const CLAUDE_PREDEFINED_MODELS: ProviderModelsDefinition = {
           { value: 'high' },
           { value: 'xhigh' },
           { value: 'max' },
+          ULTRACODE_EFFORT_OPTION,
         ],
       },
     },
@@ -132,6 +151,7 @@ export const CLAUDE_PREDEFINED_MODELS: ProviderModelsDefinition = {
           { value: 'high' },
           { value: 'xhigh' },
           { value: 'max' },
+          ULTRACODE_EFFORT_OPTION,
         ],
       },
     },
@@ -166,7 +186,15 @@ const ANSI_PATTERN = new RegExp(
   'g',
 );
 
-const extractClaudeEventModel = (event: ClaudeInitEvent, sessionId: string): string | null => {
+/**
+ * Claude Code stamps locally-synthesized rows (API-error placeholders and the
+ * like) with `model: "<synthetic>"`. Angle-bracketed values are placeholders,
+ * never real model ids, and must not be surfaced as the session's model.
+ */
+const isPlaceholderModel = (model: string): boolean => model.startsWith('<') && model.endsWith('>');
+
+/** Exported for tests. */
+export const extractClaudeEventModel = (event: ClaudeInitEvent, sessionId: string): string | null => {
   const eventSessionId = event.sessionId ?? event.session_id;
   if (eventSessionId && eventSessionId !== sessionId) {
     return null;
@@ -178,12 +206,12 @@ const extractClaudeEventModel = (event: ClaudeInitEvent, sessionId: string): str
   }
 
   const directModel = event.model?.trim();
-  if (directModel) {
+  if (directModel && !isPlaceholderModel(directModel)) {
     return directModel;
   }
 
   const messageModel = event.message?.model?.trim();
-  return messageModel || null;
+  return messageModel && !isPlaceholderModel(messageModel) ? messageModel : null;
 };
 
 const stripAnsi = (value: string): string => value.replace(ANSI_PATTERN, '');
@@ -199,13 +227,15 @@ const extractClaudeModelFromTextContent = (content: string): string | null => {
   if (localCommandStdout !== null) {
     const cleanedStdout = stripAnsi(localCommandStdout).replace(/\s+/g, ' ').trim();
     const changedModel = /(?:set|changed|switched)\s+model\s+to\s+(.+?)\.?$/i.exec(cleanedStdout);
-    if (changedModel?.[1]?.trim()) {
-      return changedModel[1].trim();
+    const stdoutModel = changedModel?.[1]?.trim();
+    // A placeholder stdout hit must not shadow a real <model> tag further down.
+    if (stdoutModel && !isPlaceholderModel(stdoutModel)) {
+      return stdoutModel;
     }
   }
 
   const modelTag = extractTaggedContent(content, 'model')?.trim();
-  return modelTag || null;
+  return modelTag && !isPlaceholderModel(modelTag) ? modelTag : null;
 };
 
 const extractClaudeModelFromMessageContent = (content: unknown): string | null => {
@@ -222,6 +252,8 @@ const extractClaudeModelFromMessageContent = (content: unknown): string | null =
       continue;
     }
 
+    // extractClaudeModelFromTextContent rejects placeholders, so a placeholder
+    // part yields null here and a later part can still supply the real model.
     const model = extractClaudeModelFromTextContent(part.text);
     if (model) {
       return model;

package/server/modules/providers/list/claude/claude-runtime.provider.js

@@ -24,7 +24,10 @@ import {
   buildClaudeUserContent,
   normalizeImageDescriptors
 } from '@/shared/image-attachments.js';
-import { CLAUDE_PREDEFINED_MODELS } from '@/modules/providers/list/claude/claude-models.provider.js';
+import {
+  CLAUDE_PREDEFINED_MODELS,
+  CLAUDE_ULTRACODE_EFFORT
+} from '@/modules/providers/list/claude/claude-models.provider.js';
 import { resolveClaudeCodeExecutablePath } from '@/shared/claude-cli-path.js';
 import {
   createNotificationEvent,
@@ -69,6 +72,12 @@ const BG_WAIT_CEILING_MS = 30 * 60 * 1000;
 
 const TOOLS_REQUIRING_INTERACTION = new Set(['AskUserQuestion', 'ExitPlanMode']);
 
+// Ultracode is a session-scoped setting rather than an SDK effort level: it pairs xhigh
+// effort with standing dynamic-workflow orchestration, and the CLI only honours it when
+// Workflows are enabled. The catalog offers it as an effort choice for the picker, so the
+// selection is translated back into the two options the SDK actually understands here.
+const ULTRACODE_SDK_EFFORT = 'xhigh';
+
 function resolveClaudeEffort(model, effort, modelsDefinition = CLAUDE_PREDEFINED_MODELS) {
   const selectedModel = modelsDefinition?.OPTIONS?.find((option) => option.value === model) || null;
   const allowedEfforts = selectedModel?.effort?.values
@@ -78,6 +87,30 @@ function resolveClaudeEffort(model, effort, modelsDefinition = CLAUDE_PREDEFINED
     : undefined;
 }
 
+/**
+ * Writes the resolved effort choice onto the SDK options, expanding `ultracode` into the
+ * xhigh effort level plus the session-scoped settings it requires.
+ * @param {Object} sdkOptions - SDK options being built
+ * @param {string|undefined} resolvedEffort - Catalog-validated effort selection
+ */
+function applyClaudeEffort(sdkOptions, resolvedEffort) {
+  if (!resolvedEffort) {
+    return;
+  }
+
+  if (resolvedEffort !== CLAUDE_ULTRACODE_EFFORT) {
+    sdkOptions.effort = resolvedEffort;
+    return;
+  }
+
+  sdkOptions.effort = ULTRACODE_SDK_EFFORT;
+  sdkOptions.settings = {
+    ...(sdkOptions.settings || {}),
+    ultracode: true,
+    enableWorkflows: true
+  };
+}
+
 function createRequestId() {
   if (typeof crypto.randomUUID === 'function') {
     return crypto.randomUUID();
@@ -183,7 +216,7 @@ function matchesToolPermission(entry, toolName, input) {
 }
 
 function mapCliOptionsToSDK(options = {}) {
-  const { providerSessionId, cwd, toolsSettings, permissionMode, effort } = options;
+  const { providerSessionId, cwd, toolsSettings, permissionMode, effort, resumeAnchorId, resumeFromScratch } = options;
 
   const sdkOptions = {};
 
@@ -193,7 +226,12 @@ function mapCliOptionsToSDK(options = {}) {
 
   // Resolve the executable eagerly on Windows because the SDK uses raw child_process.spawn,
   // which does not reliably follow npm's shell wrappers like cross-spawn does.
-  sdkOptions.pathToClaudeCodeExecutable = resolveClaudeCodeExecutablePath(process.env.CLAUDE_CLI_PATH);
+  // When nothing resolves the option stays unset on purpose: the SDK then falls back to the
+  // binary it ships, which beats handing it a bare `claude` that raw spawn can never launch.
+  const claudeExecutablePath = resolveClaudeCodeExecutablePath(process.env.CLAUDE_CLI_PATH);
+  if (claudeExecutablePath) {
+    sdkOptions.pathToClaudeCodeExecutable = claudeExecutablePath;
+  }
 
   if (cwd) {
     sdkOptions.cwd = cwd;
@@ -235,14 +273,11 @@ function mapCliOptionsToSDK(options = {}) {
 
   sdkOptions.model = options.model || CLAUDE_PREDEFINED_MODELS.DEFAULT;
 
-  const resolvedEffort = resolveClaudeEffort(
+  applyClaudeEffort(sdkOptions, resolveClaudeEffort(
     sdkOptions.model,
     effort,
     options.effortModels || CLAUDE_PREDEFINED_MODELS,
-  );
-  if (resolvedEffort) {
-    sdkOptions.effort = resolvedEffort;
-  }
+  ));
 
   sdkOptions.systemPrompt = {
     type: 'preset',
@@ -252,8 +287,19 @@ function mapCliOptionsToSDK(options = {}) {
   sdkOptions.settingSources = ['project', 'user', 'local'];
 
   // The SDK resumes with the provider-native session id, never the app id.
-  if (providerSessionId) {
+  // `resumeFromScratch` is set when the very first prompt of a conversation was
+  // edited: there is nothing before it to resume through, so the turn has to
+  // start the conversation over instead.
+  if (providerSessionId && !resumeFromScratch) {
     sdkOptions.resume = providerSessionId;
+
+    // Editing an already-sent message re-runs the conversation truncated just
+    // before it. `resumeSessionAt` is inclusive of the uuid it names, so the
+    // caller resolves the last row to KEEP and passes that — never the edited
+    // turn itself, which would leave the original prompt in context.
+    if (resumeAnchorId) {
+      sdkOptions.resumeSessionAt = resumeAnchorId;
+    }
   }
 
   return sdkOptions;
@@ -339,47 +385,129 @@ function transformMessage(sdkMessage) {
   return sdkMessage;
 }
 
+/**
+ * True for the user bubble the SDK echoes for a subagent's own prompt.
+ *
+ * Subagent traffic carries `parent_tool_use_id`, so this echo lands in the main
+ * thread and stacks a second copy of the prompt right below the Agent tool card
+ * that already displays it. It also disappears on reload, because the transcript
+ * keeps that turn in the subagent's sidechain rather than the session file.
+ * @param {Object} message - Normalized message about to be sent to the client
+ * @returns {boolean}
+ */
+export function isSubagentPromptEcho(message) {
+  return Boolean(message?.parentToolUseId) && message.role === 'user' && message.kind === 'text';
+}
+
 function readNumber(value) {
   const parsed = Number(value);
   return Number.isFinite(parsed) ? parsed : 0;
 }
 
 /**
- * Extracts token usage from SDK messages.
- * Prefers per-step `message.usage` (Claude message payload), then falls back
- * to result-level usage/modelUsage for compatibility across SDK versions.
+ * @typedef {Object} TokenBudget
+ * @property {number} used
+ * @property {number} total
+ * @property {number} inputTokens
+ * @property {number} outputTokens
+ * @property {number} [cacheReadTokens]
+ * @property {number} [cacheCreationTokens]
+ * @property {number} [cacheTokens]
+ * @property {{ input: number, output: number }} breakdown
+ */
+
+/**
+ * Builds a context-window budget from an Anthropic-shaped usage payload.
+ *
+ * `input_tokens + cache_read + cache_creation` is one request's whole prompt,
+ * which is exactly what the context window holds at that moment.
+ * @param {Object} messageUsage - Anthropic usage payload
+ * @returns {TokenBudget} Token budget object
+ */
+function buildTokenBudget(messageUsage) {
+  const directInputTokens = readNumber(messageUsage.input_tokens ?? messageUsage.inputTokens);
+  const cacheCreationTokens = readNumber(messageUsage.cache_creation_input_tokens ?? messageUsage.cacheCreationInputTokens ?? messageUsage.cacheCreationTokens);
+  const cacheReadTokens = readNumber(messageUsage.cache_read_input_tokens ?? messageUsage.cacheReadInputTokens ?? messageUsage.cacheReadTokens);
+  const cacheTokens = cacheCreationTokens + cacheReadTokens;
+  const inputTokens = directInputTokens + cacheTokens;
+  const outputTokens = readNumber(messageUsage.output_tokens ?? messageUsage.outputTokens);
+  const contextWindow = parseInt(process.env.CONTEXT_WINDOW, 10) || 160000;
+
+  return {
+    used: inputTokens + outputTokens,
+    total: contextWindow,
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheCreationTokens,
+    cacheTokens,
+    breakdown: {
+      input: inputTokens,
+      output: outputTokens,
+    },
+  };
+}
+
+/**
+ * Extracts the session's context-window usage from an SDK stream message.
+ *
+ * Only assistant messages describe the context window: each one reports the
+ * prompt its own request carried. The turn-ending `result` is deliberately not
+ * a source here — see `extractCumulativeTokenBudget`.
  * @param {Object} sdkMessage - SDK stream message
- * @returns {Object|null} Token budget object or null
+ * @returns {TokenBudget|null} Token budget object or null
  */
 function extractTokenBudget(sdkMessage) {
   if (!sdkMessage || typeof sdkMessage !== 'object') {
     return null;
   }
 
-  const messageUsage = sdkMessage.message?.usage || sdkMessage.usage;
-  if (messageUsage && typeof messageUsage === 'object') {
-    const directInputTokens = readNumber(messageUsage.input_tokens ?? messageUsage.inputTokens);
-    const cacheCreationTokens = readNumber(messageUsage.cache_creation_input_tokens ?? messageUsage.cacheCreationInputTokens ?? messageUsage.cacheCreationTokens);
-    const cacheReadTokens = readNumber(messageUsage.cache_read_input_tokens ?? messageUsage.cacheReadInputTokens ?? messageUsage.cacheReadTokens);
-    const cacheTokens = cacheCreationTokens + cacheReadTokens;
-    const inputTokens = directInputTokens + cacheTokens;
-    const outputTokens = readNumber(messageUsage.output_tokens ?? messageUsage.outputTokens);
-    const totalUsed = inputTokens + outputTokens;
-    const contextWindow = parseInt(process.env.CONTEXT_WINDOW, 10) || 160000;
+  // Subagent traffic (parent_tool_use_id set) reports the subagent's own
+  // context window, not this session's — surfacing it makes the counter drop
+  // to the subagent's number and bounce back on the next main-thread event.
+  if (sdkMessage.parent_tool_use_id) {
+    return null;
+  }
 
-    return {
-      used: totalUsed,
-      total: contextWindow,
-      inputTokens,
-      outputTokens,
-      cacheReadTokens,
-      cacheCreationTokens,
-      cacheTokens,
-      breakdown: {
-        input: inputTokens,
-        output: outputTokens,
-      },
-    };
+  // Only assistant messages carry Anthropic-shaped usage. System
+  // task_progress/task_notification events have a top-level `usage` too, but
+  // shaped {total_tokens, tool_uses, duration_ms} — reading Anthropic keys
+  // off it yields an all-zero budget that flashes "0" in the composer.
+  if (sdkMessage.type !== 'assistant') {
+    return null;
+  }
+
+  const messageUsage = sdkMessage.message?.usage;
+  if (!messageUsage || typeof messageUsage !== 'object') {
+    return null;
+  }
+
+  return buildTokenBudget(messageUsage);
+}
+
+/**
+ * Last-resort budget read from a turn's `result` message.
+ *
+ * `result.usage` and `result.modelUsage` are the turn's *bill*: every request
+ * the turn made, summed, including each subagent's. A turn that made four
+ * requests therefore reports roughly four times the context the conversation
+ * actually holds, so publishing it made the counter leap at the end of a turn
+ * and fall back on the next assistant message — worst with subagents running,
+ * whose requests inflate the sum without ever entering this session's context.
+ *
+ * It is still the only usage an SDK build that reports none per assistant
+ * message ever emits, so it stays available for the caller to use when a turn
+ * produced no assistant budget at all.
+ * @param {Object} sdkMessage - SDK stream message
+ * @returns {TokenBudget|null} Token budget object or null
+ */
+function extractCumulativeTokenBudget(sdkMessage) {
+  if (!sdkMessage || typeof sdkMessage !== 'object' || sdkMessage.type !== 'result') {
+    return null;
+  }
+
+  if (sdkMessage.usage && typeof sdkMessage.usage === 'object') {
+    return buildTokenBudget(sdkMessage.usage);
   }
 
   if (!sdkMessage.modelUsage || typeof sdkMessage.modelUsage !== 'object') {
@@ -599,6 +727,9 @@ async function queryClaudeSDK(command, options = {}, ws, context) {
   // True while the process is being held open for background work, so a later
   // `result` can be recognised as that work reporting back.
   let heldForBackgroundWork = false;
+  // Set once a turn publishes a budget read from an assistant message, so the
+  // turn-ending `result` is only mined for usage when nothing better arrived.
+  let assistantBudgetSent = false;
 
   // A new turn supersedes any earlier one still holding this session's process
   // open, so held runs cannot stack up across a conversation.
@@ -736,6 +867,13 @@ async function queryClaudeSDK(command, options = {}, ws, context) {
         return { behavior: 'deny', message: 'Permission request cancelled' };
       }
 
+      // A client answered. Announce it on the run stream so the replay buffer
+      // and every other attached tab drop the prompt — resolving happens over
+      // the inbound socket only, so without this a mid-run page refresh
+      // replays the `permission_request` with nothing to retract it and the
+      // already-answered prompt resurrects.
+      ws.send(createNormalizedMessage({ kind: 'permission_resolved', requestId, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
+
       if (decision.allow) {
         if (decision.rememberEntry && typeof decision.rememberEntry === 'string') {
           if (!sdkOptions.allowedTools.includes(decision.rememberEntry)) {
@@ -812,12 +950,21 @@ async function queryClaudeSDK(command, options = {}, ws, context) {
         if (transformedMessage.parentToolUseId && !msg.parentToolUseId) {
           msg.parentToolUseId = transformedMessage.parentToolUseId;
         }
+        if (isSubagentPromptEcho(msg)) {
+          continue;
+        }
         ws.send(msg);
       }
 
-      // Extract and send token budget updates from assistant/result usage payloads
-      const tokenBudgetData = extractTokenBudget(message);
+      // Extract and send token budget updates from assistant usage payloads,
+      // falling back to the turn's cumulative bill only for SDK builds that
+      // report no per-assistant usage at all.
+      const tokenBudgetData = extractTokenBudget(message)
+        || (assistantBudgetSent ? null : extractCumulativeTokenBudget(message));
       if (tokenBudgetData) {
+        if (message.type === 'assistant') {
+          assistantBudgetSent = true;
+        }
         ws.send(createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: tokenBudgetData, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
       }
 
@@ -1064,5 +1211,7 @@ export {
   getActiveClaudeSDKSessions,
   resolveToolApproval,
   getPendingApprovalsForSession,
-  reconnectSessionWriter
+  reconnectSessionWriter,
+  extractTokenBudget,
+  extractCumulativeTokenBudget
 };