🤖 feat: count AI calls from bash commands in workspace costs (opt-in) (#5772)

## Summary

Bash tool commands can now send their Anthropic and OpenAI calls through
Xum, so the spend shows up in the workspace's Cost tab and in Analytics.
Turn on **Settings → Providers → Bash commands** (off by default). Each
Local or Worktree bash command then gets `ANTHROPIC_BASE_URL`,
`OPENAI_BASE_URL` and a per-workspace `xum-proxy-…` key that point at a
loopback proxy. The proxy forwards with the provider keys from Xum's
settings and records the reported usage.

This is PR 1 of 4 in a stack. PR 2 keeps the port and keys stable across
restarts, PR 3 adds SSH and Coder hosts, and PR 4 adds a bug-bash
scenario for the feature.

## Background

Test harnesses (`make bug-bash`, e2e explorers, SDK scripts) that the
agent runs in bash call providers directly. Today that spend never
reaches Xum's ledger, so the Cost tab and Analytics undercount.

## Implementation

- `src/node/services/bashAiProxy/bashAiProxyService.ts`: a loopback HTTP
proxy. Allowed paths: Messages, Responses, Chat Completions, token
counting and model listing. It replaces the proxy key with the real key
and provider headers, adds `stream_options.include_usage` to streamed
Chat Completions, drops `Expect`, and does not follow redirects. It
builds the upstream URL from the configured base URL (normalized like
the chat path, query kept) and keeps headers configured in
providers.jsonc, such as `OpenAI-Project`.
- `usageExtract.ts` reads usage from JSON and SSE bodies (Anthropic and
OpenAI). The proxy records usage through
`SessionUsageService.recordHeadlessUsage` with analytics source
`bash_proxy`, and emits a live `session-usage-delta`.
- `TurnRequestBuilder` adds the variables to `xumEnv` on a best-effort
basis. It adds none when:
  - the switch is off,
  - a project secret names any of that provider's variables,
  - Xum has no API key for that provider,
- the workspace is not trusted for shared execution (untrusted project
or `XUM_DISABLE_PROJECT_AUTOMATION=1`). The bash tool blanks provider
keys there, so a proxy URL would pair with a blank key.
- The proxy checks each request. If the switch is off, it returns 503.
If the key's workspace was removed, it returns 401. If the project lost
trust, it returns 403. So commands that already hold a key lose access
at once.

## Validation

- Unit tests with a fake upstream: both Anthropic SDK path styles,
OpenAI chat and responses, SSE usage, header handling, the refusals
above, and the env rules. `aiService.test.ts` covers the trust gating
for trusted, untrusted and kill-switch workspaces. I mutation-checked it
and the 403 test.
- Dogfood with a fake provider and no real spend: a bash `curl` through
the proxy shows up in the Cost tab rows next to the chat turns.

![Cost tab with bash proxy
usage](https://github.com/user-attachments/assets/5fe78f3b-b4ea-4916-9b9c-0d8e6eac5087)

- Four agent bug-bash rounds (Opus 5.5 and Sonnet 5.5 explorers, effort
high, PR 4 scenario) against the top of the stack. The last round found
no defect in branch code. Earlier rounds found unclear setting copy and
two trust gaps. This stack fixes them.

## Risks

- With the switch on, agent CLIs such as `claude -p` bill the Xum API
key instead of a subscription login. That is why the switch is opt-in.
The docs and the setting text say so.
- Usage comes from what the provider reports. If a client disconnects
mid-stream, Xum records only the usage seen before the disconnect.

Related issues filed from the bug bashes (not fixed here): #5766, #5767,
#5768, #5769, #5771.

---

_Generated with `xum` • Model: `anthropic:claude-opus-5-5` • Thinking:
`high` • Cost: `$32.63`_

<!-- mux-attribution: model=anthropic:claude-opus-5-5 thinking=high
costs=32.63 -->

Author: ThomasK33

docs/config/providers.mdx

@@ -73,6 +73,27 @@ Azure OpenAI env vars configure the OpenAI provider with Azure backend.
 
 {/* END PROVIDER_ENV_VARS */}
 
+## AI Calls from Bash Commands
+
+Scripts that the agent runs in the bash tool (test harnesses, `make bug-bash`, SDK scripts) can call Anthropic and OpenAI directly. Turn on **Settings → Providers → Bash commands** to count that spend (it is off by default). Each bash command then gets a local endpoint and a workspace key, and Xum adds the usage to that workspace's Costs tab and to Analytics (source `headless:bash_proxy`).
+
+| Variable                                                      | Value                                 |
+| ------------------------------------------------------------- | ------------------------------------- |
+| `ANTHROPIC_BASE_URL`                                          | `http://127.0.0.1:<port>/anthropic`   |
+| `OPENAI_BASE_URL`                                             | `http://127.0.0.1:<port>/openai/v1`   |
+| `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `OPENAI_API_KEY` | `xum-proxy-…` (one key per workspace) |
+
+- Xum sends the calls with the provider keys from this page. The command never sees the real key.
+- Only Local and Worktree commands get the variables. SSH, Coder, Docker and devcontainer commands keep their environment.
+- Bash commands in `xum run` and `xum workflow` sessions do not get the variables.
+- Commands in untrusted projects, and every command while `XUM_DISABLE_PROJECT_AUTOMATION=1` is set, get no variables: Xum blanks provider keys there, so repo code cannot spend through the proxy. Revoking a project's trust also refuses calls from its commands that are still running.
+- A provider without a Xum API key (for example OpenAI with Codex OAuth only) gets no variables. A provider that your [project secrets](/config/project-secrets) configure keeps the secret values. This includes `OPENAI_ORG_ID` and `OPENAI_PROJECT_ID`.
+- The proxy allows Messages, Responses, Chat Completions, token counting and model listing. Other paths get 404.
+- The port and keys change when Xum restarts. A background command started before the restart gets connection errors. Start it again.
+- A key stops working when its workspace is removed.
+- A script that exports its own `ANTHROPIC_API_KEY` but keeps the proxy URL gets 401. Set both the key and the base URL, or neither.
+- Agent CLIs that read these variables also go through the proxy. `claude -p` in a bash command then bills the Xum Anthropic key instead of a Claude subscription login.
+
 ## Advanced: Manual Configuration
 
 For advanced options not exposed in the UI, edit `~/.xum/providers.jsonc` directly:

src/browser/features/Settings/Sections/ProvidersSection.stories.tsx

@@ -218,3 +218,24 @@ export const CoderModelRouting: Story = {
     await canvas.findByText(/openai-removed is not a known OpenAI provider/);
   },
 };
+
+/** The Bash commands switch saves through the API and stays on. */
+export const BashCommandsSwitch: Story = {
+  render: () => (
+    <SettingsSectionStory setup={() => setupSettingsStory({ providersConfig: {} })}>
+      <ProvidersSection />
+    </SettingsSectionStory>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const toggle = await canvas.findByRole(
+      "switch",
+      { name: "Count AI calls from bash commands" },
+      { timeout: 5000 }
+    );
+    await waitFor(() => expect(toggle).toHaveAttribute("aria-checked", "false"));
+    await userEvent.click(toggle);
+    // A failed save rolls the switch back.
+    await waitFor(() => expect(toggle).toHaveAttribute("aria-checked", "true"));
+  },
+};

src/browser/features/Settings/Sections/ProvidersSection.tsx

@@ -33,6 +33,7 @@ import { useWorkspaceContext } from "@/browser/contexts/WorkspaceContext";
 import { ProviderIcon, ProviderWithIcon } from "@/browser/components/ProviderIcon/ProviderIcon";
 import { getStoredAuthToken } from "@/browser/components/AuthTokenModal/AuthTokenModal";
 import { useAPI } from "@/browser/contexts/API";
+import { ConfigSwitchSetting, type SettingsApi } from "./ConfigSwitchSetting";
 import { useSettings } from "@/browser/contexts/SettingsContext";
 import { useProvidersConfig } from "@/browser/hooks/useProvidersConfig";
 import {
@@ -463,6 +464,11 @@ function GatewayRoutePriorityList({
   );
 }
 
+const loadBashAiProxyEnabled = async (api: SettingsApi) =>
+  (await api.config.getConfig()).bashAiProxyEnabled;
+const saveBashAiProxyEnabled = (api: SettingsApi, enabled: boolean) =>
+  api.config.updateBashAiProxyEnabled({ enabled });
+
 export function ProvidersSection() {
   const {
     providersExpandedProvider,
@@ -3444,6 +3450,19 @@ export function ProvidersSection() {
         </div>
       )}
 
+      <div className="space-y-2 pt-2">
+        <div className="text-muted text-xs font-medium tracking-wide uppercase">Bash commands</div>
+        <ConfigSwitchSetting
+          title="Count AI calls from bash commands"
+          description="Local and Worktree bash commands get ANTHROPIC_BASE_URL, OPENAI_BASE_URL and a workspace key that point at Xum. Xum forwards their calls with the API keys above and adds the tokens and cost to the workspace's Cost tab and to Analytics. Agent CLIs that you start in bash, such as Claude Code, then bill these API keys instead of your subscription. When off, new commands get no proxy variables, and Xum refuses calls from commands that still hold a workspace key."
+          ariaLabel="Count AI calls from bash commands"
+          placeholderChecked={false}
+          load={loadBashAiProxyEnabled}
+          save={saveBashAiProxyEnabled}
+          saveErrorMessage="Failed to update the bash AI proxy setting"
+        />
+      </div>
+
       {config && !hasAnyConfiguredProvider && (
         <div className="border-warning/40 bg-warning/10 text-warning rounded-md border px-3 py-2 text-xs">
           No providers are currently enabled. You won&apos;t be able to send messages until you

src/browser/stories/mocks/orpc.ts

@@ -600,6 +600,7 @@ export function createMockORPCClient(options: MockORPCClientOptions = {}): APICl
   let chatTranscriptFullWidth = initialChatTranscriptFullWidth;
   let keepScreenAwake = initialKeepScreenAwake;
   let toolSearchEnabled = true;
+  let bashAiProxyEnabled = false;
   let agentHeartbeatsEnabled = false;
   let runtimeEnablement: Record<string, boolean> = initialRuntimeEnablement ?? {
     local: true,
@@ -850,6 +851,7 @@ export function createMockORPCClient(options: MockORPCClientOptions = {}): APICl
           llmDebugLogs: false,
           keepScreenAwake,
           toolSearchEnabled,
+          bashAiProxyEnabled,
           agentHeartbeatsEnabled,
         }),
       saveConfig: (input: {
@@ -963,6 +965,11 @@ export function createMockORPCClient(options: MockORPCClientOptions = {}): APICl
         notifyConfigChanged();
         return Promise.resolve(undefined);
       },
+      updateBashAiProxyEnabled: (input: { enabled: boolean }) => {
+        bashAiProxyEnabled = input.enabled;
+        notifyConfigChanged();
+        return Promise.resolve(undefined);
+      },
       updateAgentHeartbeatsEnabled: (input: { enabled: boolean }) => {
         agentHeartbeatsEnabled = input.enabled;
         notifyConfigChanged();

src/browser/testUtils.ts

@@ -161,6 +161,7 @@ export function createTestConfig(overrides: Partial<TestClientConfig> = {}): Tes
     llmDebugLogs: false,
     keepScreenAwake: false,
     toolSearchEnabled: true,
+    bashAiProxyEnabled: false,
     agentHeartbeatsEnabled: false,
     goalDefaults: DEFAULT_GOAL_DEFAULTS,
     ...overrides,

src/browser/utils/commandIds.ts

@@ -105,6 +105,7 @@ export const CommandIds = {
   settingsOpen: () => "settings:open" as const,
   settingsOpenSection: (section: string) => `settings:open:${section}` as const,
   settingsToggleKeepScreenAwake: () => "settings:toggle-keep-screen-awake" as const,
+  settingsToggleBashAiProxy: () => "settings:toggle-bash-ai-proxy" as const,
   openServerWindow: () => "remote-connection:open-server-window" as const,
   coderDisconnect: () => "providers:coder:disconnect" as const,
   coderRefreshModels: () => "providers:coder:refresh-models" as const,

src/browser/utils/commands/sources.test.ts

@@ -1352,6 +1352,30 @@ test("toggle keep screen awake command inverts the persisted config flag", async
   }
 });
 
+test("toggle bash AI proxy command inverts the persisted config flag", async () => {
+  let bashAiProxyEnabled = false;
+  const updateBashAiProxyEnabled = mock((input: { enabled: boolean }) => {
+    bashAiProxyEnabled = input.enabled;
+    return Promise.resolve();
+  });
+  const actions = getActions({
+    api: createTestApiClient({
+      config: {
+        getConfig: () => Promise.resolve(createTestConfig({ bashAiProxyEnabled })),
+        updateBashAiProxyEnabled,
+      },
+    }),
+  });
+  const toggleAction = actions.find((a) => a.id === "settings:toggle-bash-ai-proxy");
+
+  expect(toggleAction).toBeDefined();
+  await toggleAction!.run();
+  expect(updateBashAiProxyEnabled).toHaveBeenLastCalledWith({ enabled: true });
+  await toggleAction!.run();
+  expect(updateBashAiProxyEnabled).toHaveBeenLastCalledWith({ enabled: false });
+  expect(bashAiProxyEnabled).toBe(false);
+});
+
 test("analytics rebuild command calls route and dispatches toast feedback", async () => {
   const rebuildDatabase = mock(() => Promise.resolve({ success: true, workspacesIngested: 4 }));
 

src/browser/utils/commands/sources.ts

@@ -2043,6 +2043,23 @@ export function buildCoreSources(p: BuildSourcesParams): Array<() => CommandActi
         ]
   );
 
+  // Keyboard route for the Settings → Providers → Bash commands switch.
+  actions.push(() => [
+    {
+      id: CommandIds.settingsToggleBashAiProxy(),
+      title: "Toggle Count AI Calls from Bash Commands",
+      subtitle: "Route bash commands' Anthropic and OpenAI calls through Xum to count their cost",
+      section: section.settings,
+      keywords: ["bash", "proxy", "cost", "usage", "anthropic", "openai", "billing"],
+      run: async () => {
+        if (!p.api) return;
+        // The flag lives in config.json (not localStorage), so read the current value first.
+        const cfg = await p.api.config.getConfig();
+        await p.api.config.updateBashAiProxyEnabled({ enabled: !cfg.bashAiProxyEnabled });
+      },
+    },
+  ]);
+
   // Settings
   if (p.onOpenSettings) {
     const openSettings = p.onOpenSettings;

src/common/config/schemas/appConfigOnDisk.ts

@@ -177,6 +177,8 @@ export const AppConfigOnDiskSchema = z
     keepScreenAwake: z.boolean().optional(),
     /** Defer MCP tool definitions behind tool_catalog_search. Absent = on. */
     toolSearchEnabled: z.boolean().optional(),
+    /** Route AI calls from bash tool commands through Xum's cost-tracking proxy. Absent = off. */
+    bashAiProxyEnabled: z.boolean().optional(),
     /** Expose the `heartbeat` tool so agents can schedule their own recurring turns. Absent = off. */
     agentHeartbeatsEnabled: z.boolean().optional(),
     heartbeatDefaultPrompt: z.string().optional(),

src/common/orpc/schemas/api.ts

@@ -3149,6 +3149,7 @@ export const config = {
       llmDebugLogs: z.boolean(),
       keepScreenAwake: z.boolean(),
       toolSearchEnabled: z.boolean(),
+      bashAiProxyEnabled: z.boolean(),
       agentHeartbeatsEnabled: z.boolean(),
       heartbeatDefaultPrompt: z.string().optional(),
       heartbeatDefaultIntervalMs: z.number().optional(),
@@ -3287,6 +3288,7 @@ export const config = {
   updateLlmDebugLogs: booleanToggleRoute,
   updateKeepScreenAwake: booleanToggleRoute,
   updateToolSearchEnabled: booleanToggleRoute,
+  updateBashAiProxyEnabled: booleanToggleRoute,
   updateAgentHeartbeatsEnabled: booleanToggleRoute,
   updateHeartbeatDefaultPrompt: {
     input: z