@askalf/dario 3.31.20 → 3.32.0

package/README.md

@@ -281,7 +281,9 @@ Dario's built-in `TOOL_MAP` carries **~66 schema-verified entries** covering the
 | OpenClaw | `exec`, `process`, `web_search`, `web_fetch`, `browser`, `message` |
 | Hermes Agent (Nous Research) | `terminal`, `process`, `read_file`, `write_file`, `patch`, `search_files`, `web_search`, `web_extract`, `todo` mapped directly. Hermes-specific tools (`browser_*`, `vision_analyze`, `image_generate`, `skill_*`, `memory`, `session_search`, `cronjob`, `send_message`, `ha_*`, `mixture_of_agents`, `delegate_task`, `execute_code`, `text_to_speech`) have no CC equivalent and auto-preserve through the identity detector (`You are Hermes Agent` or `created by Nous Research` in the system prompt flips dario into preserve-tools for Hermes sessions automatically — v3.30.13). Also consider `--max-tokens=client` so Hermes's 64k/128k per-model caps survive dario's outbound pin. |
 
-Text-tool clients (Cline / Kilo Code / Roo Code and forks) are auto-detected via system-prompt identity markers and automatically flipped into preserve-tools mode, because mixing CC's `tools` array with their XML protocol makes the model emit `<function_calls><invoke>` that their parsers can't read. If you run dario specifically for wire-level fidelity and would rather pick `--preserve-tools` yourself, `--no-auto-detect` (v3.20.1, aka `--no-auto-preserve`) disables the heuristic — explicit operator choice then wins.
+Text-tool clients (Cline / Kilo Code / Roo Code and forks) are auto-detected via system-prompt identity markers and automatically flipped into preserve-tools mode, because mixing CC's `tools` array with their XML protocol makes the model emit `<function_calls><invoke>` that their parsers can't read. The same identity path also catches `arnie` (askalf's portable IT-troubleshooting CLI) — its tool names overlap with `TOOL_MAP` but its schemas diverge, so identity match → preserve-tools is the only correct routing. If you run dario specifically for wire-level fidelity and would rather pick `--preserve-tools` yourself, `--no-auto-detect` (v3.20.1, aka `--no-auto-preserve`) disables the heuristic — explicit operator choice then wins.
+
+Beyond the identity path, dario falls back to a **structural** check: when a request carries 3+ tools and ≥80% of them aren't in `TOOL_MAP`, that's a custom client whose tool surface has effectively no overlap with CC's, and round-robin remap onto CC fallback slots silently corrupts the calls. The structural fallback flips those requests to preserve-tools too, with `client: 'unknown-non-cc'` in the request log. This catches in-house agents and OpenClaw derivatives that we haven't added an explicit pattern for, without needing per-client maintenance. `--no-auto-detect` disables both paths.
 
 If your agent's tool names aren't pre-mapped and its tools carry fields CC's schema doesn't have, there are two escape hatches: **`--preserve-tools`** (forward your schema verbatim, lose the CC wire shape) or **`--hybrid-tools`** (keep the CC wire shape, fill request-context fields from headers). See [Custom tool schemas](#custom-tool-schemas).
 
@@ -336,7 +338,8 @@ A version marker (`<!-- dario-sub-agent-version: X -->`) embedded in the markdow
 |---|---|
 | `dario login [--manual]` | Log in to the Claude backend. Detects CC credentials or runs its own OAuth flow. `--manual` (v3.20) mirrors CC's code-paste flow for SSH / container setups without a browser. |
 | `dario proxy` | Start the local API proxy on port 3456 |
-| `dario doctor [--probe] [--auth-check] [--json]` | Aggregated health report — dario / Node / runtime-TLS / CC binary + compat / template + drift / OAuth / pool / backends / sub-agent. `--probe` (v3.31.7) hits the live `claude.ai/oauth/authorize` endpoint and surfaces the verdict, so scope-policy drift is catchable from a user's machine (not just CI). `--auth-check` (v3.31.9) opens a one-shot `x-api-key` listener and classifies whatever a client actually sends (match / mismatch / no-auth / timeout), with only redacted previews in output. `--json` (v3.31.8) emits structured output for claude-bridge's `/status`, deepdive's health probes, and CI scrapers. |
+| `dario doctor [--probe] [--auth-check] [--json] [--bun-bootstrap]` | Aggregated health report — dario / Node / runtime-TLS / CC binary + compat / template + drift / **per-request overhead** / OAuth / pool + **pool routing** (next account in rotation when 2+ loaded) / backends / sub-agent. `--probe` (v3.31.7) hits the live `claude.ai/oauth/authorize` endpoint and surfaces the verdict, so scope-policy drift is catchable from a user's machine (not just CI). `--auth-check` (v3.31.9) opens a one-shot `x-api-key` listener and classifies whatever a client actually sends (match / mismatch / no-auth / timeout), with only redacted previews in output. `--json` (v3.31.8) emits structured output for claude-bridge's `/status`, deepdive's health probes, and CI scrapers. `--bun-bootstrap` runs the canonical bun.sh installer when the runtime/TLS check is warning that Bun isn't on PATH. |
+| `dario usage [--port=N] [--json]` | Burn-rate summary of the running proxy's traffic over the last 60 minutes: requests, input/output tokens, avg latency, error rate, subscription % vs. extra-usage, estimated API-equivalent cost, plus per-account breakdown when pool mode is active. Hits `/analytics` on the local proxy. When the proxy isn't reachable, prints a hint pointing at `dario doctor --usage` (the one-off rate-limit probe). `--json` emits the raw `/analytics` payload for status bars / CI dashboards. Also exposed as the `usage` tool in `dario mcp`. |
 | `dario config [--json]` | Prints the effective dario configuration with credentials redacted. Complementary to `doctor` — doctor answers *is it working?*, config answers *what IS it?* (v3.31.10) |
 | `dario upgrade` | Safe wrapper over `npm install -g @askalf/dario@latest` — probes npm for the `@latest` version first (3s timeout, 60s cache), refuses to run if already on latest, fails with a clear hint if npm is missing. (v3.31.10) |
 | `dario status` | Show Claude backend OAuth token health and expiry |
@@ -357,11 +360,14 @@ A version marker (`<!-- dario-sub-agent-version: X -->`) embedded in the markdow
 | `--preserve-tools` / `--keep-tools` | Keep client tool schemas instead of remapping to CC's. Required for clients whose tools have fields CC doesn't — see [Custom tool schemas](#custom-tool-schemas). Auto-enabled for Cline / Kilo Code / Roo Code and forks (detected via system-prompt identity markers). | off (auto for text-tool clients) |
 | `--no-auto-detect` / `--no-auto-preserve` | Disable the text-tool-client detector so the CC wire shape stays intact on Cline/Kilo/Roo prompts (v3.20.1, dario#40). Explicit `--preserve-tools` still wins. | off |
 | `--hybrid-tools` / `--context-inject` | Remap to CC tools **and** inject request-context values (`sessionId`, `requestId`, `channelId`, `userId`, `timestamp`) into client-declared fields CC's schema doesn't carry. See [Hybrid tool mode](#hybrid-tool-mode). | off |
+| `--merge-tools` / `--append-tools` | **EXPERIMENTAL.** Send CC's canonical tools first, append the client's custom tools after (deduped by name, case-insensitive). Model can call either side; tool calls flow back unchanged. Mutually exclusive with `--preserve-tools` and `--hybrid-tools`. Anthropic's billing classifier may flip routing on the appended suffix — validate with `--verbose` and watch the `billing: <bucket>` line on the first 1-2 requests before relying on it. | off |
 | `--model=<name>` | Force a model. Shortcuts (`opus`, `sonnet`, `haiku`), full IDs (`claude-opus-4-7`), or a **provider prefix** (`openai:gpt-4o`, `groq:llama-3.3-70b`, `claude:opus`, `local:qwen-coder`) to force the backend server-wide. | passthrough |
 | `--port=<n>` | Port to listen on | `3456` |
 | `--host=<addr>` / `DARIO_HOST` | Bind address. Use `0.0.0.0` for LAN, or a specific IP (e.g. a Tailscale interface). When non-loopback, also set `DARIO_API_KEY`. | `127.0.0.1` |
 | `--verbose` / `-v` | Log every request (one line per request — method + path + billing bucket) | off |
 | `--verbose=2` / `-vv` / `DARIO_LOG_BODIES=1` | Also dump the outbound request body (redacted: bearer tokens, `sk-ant-*` keys, JWTs stripped; capped at 8KB). For wire-level client-compat debugging. | off |
+| `--log-file=<path>` / `DARIO_LOG_FILE` | Append one JSON-ND record per completed request to PATH. Useful for backgrounded proxies where stdout is unobserved (where `--verbose` can't help). Field set: `ts`, `req`, `method`, `path`, `model`, `status`, `latency_ms`, `in_tokens`, `out_tokens`, `cache_read`, `cache_create`, `claim`, `bucket`, `account`, `client`, `preserve_tools`, `stream`, plus `reject` / `error` on failure paths. Secrets scrubbed via the same redactor that `--verbose-bodies` uses; no request bodies. | off |
+| `--passthrough-betas=<csv>` / `DARIO_PASSTHROUGH_BETAS` | Beta flags ALWAYS forwarded upstream regardless of CC's captured set or the client's `anthropic-beta` header. Bypasses the billable-beta filter (so `extended-cache-ttl-*` survives if you opt in). Per-account rejection cache still applies — a pinned flag the upstream 400's gets dropped on retry rather than re-sent forever. Use when you know a beta works on your account but isn't in the captured template, or when client traffic should be force-augmented. Empty flag value (`--passthrough-betas=`) clears the env-default. | off |
 | `--strict-tls` / `DARIO_STRICT_TLS=1` | Refuse to start proxy mode unless runtime classifies as `bun-match` — i.e. the TLS ClientHello matches CC's. See [Wire-fidelity axes](#wire-fidelity-axes). (v3.23) | off |
 | `--pace-min=<ms>` / `DARIO_PACE_MIN_MS` | Minimum inter-request gap in ms. Replaces the legacy hardcoded 500 ms. (v3.24) | `500` |
 | `--pace-jitter=<ms>` / `DARIO_PACE_JITTER_MS` | Uniform random jitter added to each gap. Dissolves the minimum-inter-arrival observable edge. (v3.24) | `0` |

package/dist/cc-oauth-detect.js

@@ -116,6 +116,12 @@ function candidatePaths() {
     const home = homedir();
     if (platform() === 'win32') {
         return [
+            // CC v2.x ships a Bun-compiled standalone exe under bin/.
+            // Earlier (v1.x) layouts used cli.js / cli.mjs at the package
+            // root. Both are kept in the search list so we work across the
+            // upgrade without forcing every user onto a fresh capture.
+            join(home, 'AppData', 'Roaming', 'npm', 'node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe'),
+            join(home, '.claude', 'local', 'node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe'),
             join(home, '.local', 'bin', 'claude.exe'),
             join(home, 'AppData', 'Roaming', 'npm', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
             join(home, 'AppData', 'Roaming', 'npm', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.mjs'),
@@ -124,6 +130,10 @@ function candidatePaths() {
         ];
     }
     return [
+        // v2.x bin/claude precompiled exe — checked before legacy cli.js/.mjs.
+        '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude',
+        '/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/bin/claude',
+        join(home, '.claude', 'local', 'node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude'),
         join(home, '.local', 'bin', 'claude'),
         '/usr/local/bin/claude',
         '/opt/homebrew/bin/claude',

package/dist/cc-template.d.ts

@@ -120,6 +120,30 @@ export declare function scrubFrameworkIdentifiers(text: string): string;
  * Reported via @vmvarg4 on X after the v3.30.5 marketing push.
  */
 export declare function detectTextToolClient(systemText: string): string | null;
+/**
+ * Structural fallback for non-CC clients that the identity-string
+ * detector doesn't recognize. When the operator hands us 3+ tools and
+ * ≥80% of them don't appear in TOOL_MAP, we're looking at a custom
+ * client whose tool surface has effectively no overlap with CC's.
+ * Default-mode round-robin onto CC fallback slots silently corrupts
+ * those calls (the client gets back a Glob/Read/Bash response shape
+ * its own tool can't parse).
+ *
+ * Returns 'unknown-non-cc' for that case so buildCCRequest can flip
+ * to preserve-tools — the only correct routing for a tool surface
+ * dario doesn't understand. Unlike the identity-string detector, this
+ * catches future clients we haven't added an explicit pattern for
+ * (in-house agents, OpenClaw derivatives, etc.) without needing
+ * per-client maintenance.
+ *
+ * Threshold reasoning:
+ * - len < 3: too few tools to be confident; let the existing detector
+ *   decide. Single-purpose bridges and partial loads land here.
+ * - 80% unmapped: leaves room for a non-CC client that legitimately
+ *   reuses 1-2 of TOOL_MAP's bash/grep/read aliases. 100% would miss
+ *   those; 50% would catch Cline forks that use 4 mapped + 4 custom.
+ */
+export declare function detectNonCCByTools(clientTools: Array<Record<string, unknown>> | undefined): string | null;
 /**
  * Flatten an Anthropic-shaped `system` field (string or array of text
  * blocks) to a single joined string. Skips the billing-tag block so
@@ -218,6 +242,7 @@ export declare function buildCCRequest(clientBody: Record<string, unknown>, bill
 }, opts?: {
     preserveTools?: boolean;
     hybridTools?: boolean;
+    mergeTools?: boolean;
     noAutoDetect?: boolean;
     effort?: EffortValue;
     maxTokens?: number | 'client';

package/dist/cc-template.js

@@ -245,6 +245,16 @@ export function detectTextToolClient(systemText) {
         return 'hermes';
     if (/\bcreated by Nous Research\b/.test(systemText))
         return 'hermes';
+    // arnie (askalf) — IT-troubleshooting CLI built on the Anthropic SDK.
+    // Identity line is stable across versions ("You are Arnie, a portable
+    // IT tech troubleshooting assistant ..."). Tool *names* (shell, read_file,
+    // grep, ...) overlap with TOOL_MAP so structural fallback won't catch it,
+    // but the *schemas* diverge from CC's (arnie's shell takes {cmd, timeout_s,
+    // working_directory}; CC's Bash takes {command, description}) so default
+    // round-robin remap silently corrupts the calls. Identity match → auto
+    // preserve-tools is the only correct routing.
+    if (/\bYou are Arnie\b/.test(systemText))
+        return 'arnie';
     // Protocol-signature fallback — unique to the Cline family and its
     // forks; survives a forked system prompt that edited the identity
     // string out but kept the tool protocol intact.
@@ -256,6 +266,43 @@ export function detectTextToolClient(systemText) {
         return 'cline-like';
     return null;
 }
+/**
+ * Structural fallback for non-CC clients that the identity-string
+ * detector doesn't recognize. When the operator hands us 3+ tools and
+ * ≥80% of them don't appear in TOOL_MAP, we're looking at a custom
+ * client whose tool surface has effectively no overlap with CC's.
+ * Default-mode round-robin onto CC fallback slots silently corrupts
+ * those calls (the client gets back a Glob/Read/Bash response shape
+ * its own tool can't parse).
+ *
+ * Returns 'unknown-non-cc' for that case so buildCCRequest can flip
+ * to preserve-tools — the only correct routing for a tool surface
+ * dario doesn't understand. Unlike the identity-string detector, this
+ * catches future clients we haven't added an explicit pattern for
+ * (in-house agents, OpenClaw derivatives, etc.) without needing
+ * per-client maintenance.
+ *
+ * Threshold reasoning:
+ * - len < 3: too few tools to be confident; let the existing detector
+ *   decide. Single-purpose bridges and partial loads land here.
+ * - 80% unmapped: leaves room for a non-CC client that legitimately
+ *   reuses 1-2 of TOOL_MAP's bash/grep/read aliases. 100% would miss
+ *   those; 50% would catch Cline forks that use 4 mapped + 4 custom.
+ */
+export function detectNonCCByTools(clientTools) {
+    if (!clientTools || clientTools.length < 3)
+        return null;
+    let unmapped = 0;
+    for (const tool of clientTools) {
+        const name = (tool.name || '').toLowerCase();
+        if (!TOOL_MAP[name])
+            unmapped++;
+    }
+    if (unmapped / clientTools.length >= 0.8) {
+        return 'unknown-non-cc';
+    }
+    return null;
+}
 /**
  * Flatten an Anthropic-shaped `system` field (string or array of text
  * blocks) to a single joined string. Skips the billing-tag block so
@@ -789,8 +836,8 @@ export function buildCCRequest(clientBody, billingTag, cacheControl, identity, o
     // Cline / Kilo Code / Roo Code (and forks) ship an XML tool-invocation
     // protocol in the system prompt. Peek at it before scrubbing so the
     // brand name is still present, decide whether to auto-switch into
-    // preserve-tools behavior below. Explicit --hybrid-tools outranks the
-    // heuristic (operator opt-in wins). dario#40.
+    // preserve-tools behavior below. Explicit --hybrid-tools / --merge-tools
+    // outrank the heuristic (operator opt-in wins). dario#40.
     //
     // `noAutoDetect` skips the detector entirely — operators who want the
     // full CC fingerprint restored (tools array included) even when their
@@ -799,9 +846,22 @@ export function buildCCRequest(clientBody, billingTag, cacheControl, identity, o
     const rawSystemForDetection = extractSystemText(clientBody);
     const detectedClient = opts.noAutoDetect
         ? undefined
-        : (detectTextToolClient(rawSystemForDetection) ?? undefined);
-    const autoPreserve = Boolean(detectedClient) && !opts.hybridTools;
+        : (detectTextToolClient(rawSystemForDetection)
+            ?? detectNonCCByTools(clientTools)
+            ?? undefined);
+    const autoPreserve = Boolean(detectedClient) && !opts.hybridTools && !opts.mergeTools;
     const effectivePreserveTools = Boolean(opts.preserveTools) || autoPreserve;
+    // Merge mode is the third tool-routing axis. Wire shape: CC's canonical
+    // tool array is sent first (so the fingerprint axis "tools[]" still
+    // matches CC's wire footprint), and the client's tools are appended
+    // after — deduped by name, case-insensitive. The model sees the union
+    // and may call either side; tool calls flow back unchanged because we
+    // skip the reverse-map (any rewriting would be lossy in both directions).
+    //
+    // Mutually exclusive with preserveTools and hybridTools — three flags
+    // would mean three different bodies; the operator must pick one. The
+    // proxy CLI enforces the mutex at startup, this just respects it.
+    const effectiveMergeTools = Boolean(opts.mergeTools) && !effectivePreserveTools && !opts.hybridTools;
     // ── Strip thinking from history ──
     for (const msg of messages) {
         if (msg.role === 'assistant' && Array.isArray(msg.content)) {
@@ -844,7 +904,7 @@ export function buildCCRequest(clientBody, billingTag, cacheControl, identity, o
     // the fingerprint risk on their own account.
     const activeToolMap = new Map();
     const unmappedTools = [];
-    if (clientTools && !effectivePreserveTools) {
+    if (clientTools && !effectivePreserveTools && !effectiveMergeTools) {
         // Two passes so the unmapped-tool distributor can avoid colliding with
         // CC tools the client already uses directly. Without this, a client
         // sending both `WebSearch` and some unmapped tool like `memory_get`
@@ -1027,10 +1087,38 @@ export function buildCCRequest(clientBody, billingTag, cacheControl, identity, o
         ],
     };
     // Tools come before metadata in CC's key order.
-    // preserveTools mode: pass client tools through unchanged (better for real
-    // agents with custom schemas, but loses the CC tool fingerprint).
+    // - preserveTools mode: pass client tools through unchanged (better for
+    //   real agents with custom schemas, but loses the CC tool fingerprint).
+    // - mergeTools mode: send CC's canonical tools FIRST then append the
+    //   client's tools, deduped by name (case-insensitive). The model sees
+    //   the union; tool calls flow back unchanged because activeToolMap is
+    //   empty in this branch. Trade-off documented in the README: the
+    //   wire-shape "tools[]" axis still contains CC's array as a prefix,
+    //   but the suffix is operator-supplied custom shapes — Anthropic's
+    //   classifier may flip routing on the difference. Verify locally
+    //   before relying on it.
     if (clientTools && clientTools.length > 0) {
-        ccRequest.tools = effectivePreserveTools ? clientTools : CC_TOOL_DEFINITIONS;
+        if (effectivePreserveTools) {
+            ccRequest.tools = clientTools;
+        }
+        else if (effectiveMergeTools) {
+            const ccNames = new Set(CC_TOOL_DEFINITIONS.map((t) => t.name.toLowerCase()));
+            const appended = clientTools.filter((t) => {
+                const name = t.name?.toLowerCase();
+                return name !== undefined && !ccNames.has(name);
+            });
+            ccRequest.tools = [...CC_TOOL_DEFINITIONS, ...appended];
+        }
+        else {
+            ccRequest.tools = CC_TOOL_DEFINITIONS;
+        }
+    }
+    else if (effectiveMergeTools) {
+        // Operator opted into merge but the client sent no tools. Still
+        // emit the CC base array — that preserves the fingerprint shape
+        // (zero-tools requests are themselves a divergence from CC's
+        // wire footprint).
+        ccRequest.tools = CC_TOOL_DEFINITIONS;
     }
     // Metadata
     ccRequest.metadata = {

package/dist/cli.d.ts

@@ -10,6 +10,19 @@
  *   dario logout    — Remove saved credentials
  */
 import { type EffortValue } from './cc-template.js';
+/**
+ * Parse `--passthrough-betas=<csv>` (or the env-var fallback) into a
+ * deduped, trimmed list. The CLI flag wins over the env var when both
+ * are set — that's the convention every other dario flag uses.
+ *
+ * Edge cases:
+ *   - `--passthrough-betas=`  (explicit empty) → returns []. The
+ *     operator typed an empty value; this is the documented "clear the
+ *     env-default, run with no pinned betas" override.
+ *   - flag missing entirely → falls back to envVar.
+ *   - empty entries / whitespace-only entries / duplicates are dropped.
+ */
+export declare function parsePassthroughBetasFlag(args: string[], envVar: string | undefined): string[];
 /**
  * Parse `--max-tokens=<N|client>` + `DARIO_MAX_TOKENS` env (dario#88).
  * Numeric values pin; `client` (case-insensitive) = passthrough client's

package/dist/cli.js

@@ -181,8 +181,19 @@ async function proxy() {
     const passthrough = args.includes('--passthrough') || args.includes('--thin');
     const preserveTools = args.includes('--preserve-tools') || args.includes('--keep-tools');
     const hybridTools = args.includes('--hybrid-tools') || args.includes('--context-inject');
-    if (preserveTools && hybridTools) {
-        console.error('[dario] --preserve-tools and --hybrid-tools are mutually exclusive. Pick one.');
+    const mergeTools = args.includes('--merge-tools') || args.includes('--append-tools');
+    // The three modes shape the outbound `tools` array differently;
+    // combining any two would mean two different bodies. Caught here so
+    // the operator gets a clear error instead of one flag silently
+    // winning. startProxy enforces the same mutex defensively.
+    const toolModeCount = [preserveTools, hybridTools, mergeTools].filter(Boolean).length;
+    if (toolModeCount > 1) {
+        const picked = [
+            preserveTools && '--preserve-tools',
+            hybridTools && '--hybrid-tools',
+            mergeTools && '--merge-tools',
+        ].filter(Boolean).join(', ');
+        console.error(`[dario] tool-routing flags are mutually exclusive. Pick one (got: ${picked}).`);
         process.exit(1);
     }
     // Opt-out for v3.19.3's text-tool-client auto-detection. Operators who
@@ -268,6 +279,17 @@ async function proxy() {
     // the server side, so passing through a too-high value returns a clean
     // 400 rather than silently accepting beyond-model-max.
     const maxTokens = resolveMaxTokensFlag(args, process.env['DARIO_MAX_TOKENS']);
+    // --log-file <path> — append a one-line JSON record per completed
+    // request. Useful for backgrounded proxies where stdout is unobserved.
+    // Falls back to DARIO_LOG_FILE; off by default. Path is opened with
+    // append mode so multiple proxy restarts share a rolling history.
+    const logFile = parseLogFileFlag(args) ?? process.env['DARIO_LOG_FILE'] ?? undefined;
+    // --passthrough-betas=name1,name2 — operator-pinned beta allow-list.
+    // Names listed here are always forwarded to Anthropic regardless of
+    // CC's captured set or the client's own beta header; bypasses the
+    // billable-filter. Empty values are dropped. Falls back to
+    // DARIO_PASSTHROUGH_BETAS env var.
+    const passthroughBetas = parsePassthroughBetasFlag(args, process.env['DARIO_PASSTHROUGH_BETAS']);
     // Non-loopback bind without DARIO_API_KEY turns dario into an open
     // OAuth-subscription relay for anyone on the reachable network. Refuse
     // to start rather than rely on the operator to read the startup banner.
@@ -287,7 +309,56 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, effort, maxTokens });
+    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, effort, maxTokens, logFile, passthroughBetas });
+}
+/**
+ * Parse `--passthrough-betas=<csv>` (or the env-var fallback) into a
+ * deduped, trimmed list. The CLI flag wins over the env var when both
+ * are set — that's the convention every other dario flag uses.
+ *
+ * Edge cases:
+ *   - `--passthrough-betas=`  (explicit empty) → returns []. The
+ *     operator typed an empty value; this is the documented "clear the
+ *     env-default, run with no pinned betas" override.
+ *   - flag missing entirely → falls back to envVar.
+ *   - empty entries / whitespace-only entries / duplicates are dropped.
+ */
+export function parsePassthroughBetasFlag(args, envVar) {
+    const eqArg = args.find((a) => a.startsWith('--passthrough-betas='));
+    // When the flag is present at all (even with an empty value), it owns
+    // the result. Only fall back to the env var when the flag is absent.
+    const raw = eqArg !== undefined ? eqArg.slice('--passthrough-betas='.length) : envVar;
+    if (!raw)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const piece of raw.split(',')) {
+        const trimmed = piece.trim();
+        if (trimmed.length > 0 && !seen.has(trimmed)) {
+            seen.add(trimmed);
+            out.push(trimmed);
+        }
+    }
+    return out;
+}
+/**
+ * Parse `--log-file=<path>` or `--log-file <path>`. Returns the path
+ * string when present, undefined otherwise. An empty path (e.g.
+ * `--log-file=`) is treated as unset so the env-var fallback can apply.
+ */
+function parseLogFileFlag(args) {
+    const eqArg = args.find(a => a.startsWith('--log-file='));
+    if (eqArg) {
+        const value = eqArg.slice('--log-file='.length);
+        return value.length > 0 ? value : undefined;
+    }
+    const idx = args.indexOf('--log-file');
+    if (idx >= 0 && idx + 1 < args.length) {
+        const value = args[idx + 1];
+        if (value && !value.startsWith('-'))
+            return value;
+    }
+    return undefined;
 }
 /**
  * Parse `--max-tokens=<N|client>` + `DARIO_MAX_TOKENS` env (dario#88).
@@ -671,11 +742,30 @@ async function help() {
                              DARIO_API_KEY — with redacted previews and
                              a targeted diagnosis (dario#97 class). Use
                              --timeout-ms=N to adjust the 30s default.
+    dario doctor --bun-bootstrap
+                             One-shot Bun installer. Closes the gap
+                             between "doctor warned about Node-only TLS
+                             fingerprint" and "Bun on PATH" without
+                             copy-pasting a curl-to-shell line. Skips
+                             when Bun is already installed. Pure
+                             delegation to the official installer at
+                             bun.com — dario does not vendor or pin a
+                             Bun version.
     dario config             Print the effective configuration (port,
                              host, DARIO_API_KEY state, OAuth status,
                              pool, backends, paths) with credentials
                              redacted. Safe to paste into bug reports.
                              --json for structured output.
+    dario usage              Burn-rate summary of the running proxy's
+                             traffic (last 60 min): requests, token
+                             totals, subscription % vs. extra-usage,
+                             per-account rotation if pool mode is on.
+                             Hits /analytics on the local proxy. Works
+                             only when proxy is running; for a one-off
+                             rate-limit snapshot from Anthropic, see
+                             \`dario doctor --usage\`. --port=N to target
+                             a non-default port; --json for the raw
+                             /analytics payload.
     dario upgrade            npm install -g @askalf/dario@latest with a
                              pre-flight current-vs-latest check.
 
@@ -691,6 +781,14 @@ async function help() {
                              Loses subscription routing; use for custom agents
     --hybrid-tools           Remap to CC tools, inject sessionId/requestId/etc.
                              Keeps subscription routing for custom agents
+    --merge-tools            Send CC's canonical tools first, append the
+                             client's custom tools after (deduped by name).
+                             Model can call either; tool calls flow back
+                             unchanged. EXPERIMENTAL — Anthropic's billing
+                             classifier may flip routing on the appended
+                             tail. Validate with --verbose on the first
+                             1-2 requests. Mutually exclusive with
+                             --preserve-tools and --hybrid-tools.
     --no-auto-detect         Disable Cline/Kilo/Roo auto-preserve-tools
                              (v3.19.3 behavior). Keeps CC fingerprint
                              intact even when a text-tool client is
@@ -801,6 +899,20 @@ async function help() {
     --verbose, -v            Log all requests
     --verbose=2, -vv         Also dump redacted request bodies
                              (env: DARIO_LOG_BODIES=1)
+    --log-file=PATH          Append one JSON-ND record per completed
+                             request to PATH. Useful for backgrounded
+                             proxies where stdout is unobserved (where
+                             --verbose can't help). Secrets scrubbed,
+                             no request bodies. Env: DARIO_LOG_FILE.
+    --passthrough-betas=CSV  Beta flags to ALWAYS forward upstream
+                             regardless of CC's captured set or the
+                             client's anthropic-beta header. Bypasses
+                             the billable-beta filter. Per-account
+                             rejection cache still applies (so a flag
+                             upstream 400's gets dropped, not retried
+                             forever). Use when you know a beta works
+                             on your account but isn't in the captured
+                             template. Env: DARIO_PASSTHROUGH_BETAS.
 
   Quick start:
     dario login              # auto-detects Claude Code credentials
@@ -982,6 +1094,53 @@ async function doctor() {
     const usage = args.includes('--usage');
     const asJson = args.includes('--json');
     const authCheck = args.includes('--auth-check');
+    const bunBoot = args.includes('--bun-bootstrap');
+    if (bunBoot) {
+        // One-shot Bun installer. Closes the gap between "doctor warned
+        // about Node-only TLS fingerprint" and "Bun is on PATH" without
+        // making the user copy-paste a curl line from the README.
+        // Probe first so we don't reinstall on a Bun-already-present host.
+        const { probeBunVersion, bunBootstrap } = await import('./runtime-fingerprint.js');
+        console.log('');
+        console.log('  dario — Bun bootstrap');
+        console.log('  ─────────────────────');
+        console.log('');
+        const existing = probeBunVersion();
+        if (existing) {
+            console.log(`  Bun v${existing} already on PATH — nothing to install.`);
+            console.log('  If dario is still running on Node, the auto-relaunch was bypassed (DARIO_NO_BUN set,');
+            console.log('  or invoked through a wrapper that strips it). Re-run \`dario proxy\` directly.');
+            console.log('');
+            return;
+        }
+        console.log('  Bun is not on PATH. Running the official upstream installer:');
+        console.log('');
+        const result = await bunBootstrap();
+        console.log('');
+        if (result.exitCode === 0) {
+            // Probe again — installer may write into a directory that the
+            // current shell doesn't have on PATH yet (typical: ~/.bun/bin
+            // appended to a profile that hasn't reloaded). We can't fix that
+            // for the running shell; just call it out so the user knows what
+            // to do next.
+            const after = probeBunVersion();
+            if (after) {
+                console.log(`  Bun v${after} installed. Re-run \`dario proxy\` to auto-relaunch under it.`);
+            }
+            else {
+                console.log('  Installer reported success, but \`bun --version\` still fails from this shell.');
+                console.log('  Open a new terminal (or source the profile the installer touched), then re-run');
+                console.log('  \`dario doctor\` to confirm.');
+            }
+            console.log('');
+            return;
+        }
+        console.error(`  Installer exited with code ${result.exitCode}.`);
+        console.error(`  Manual fallback: ${result.runner}`);
+        console.error('  Or visit https://bun.com for platform-specific instructions.');
+        console.error('');
+        process.exit(result.exitCode);
+    }
     if (authCheck) {
         console.log('');
         console.log('  dario — Auth Check');
@@ -1133,6 +1292,112 @@ async function upgrade() {
     console.log('  Upgrade complete. Run `dario --version` to confirm.');
     console.log('');
 }
+/**
+ * `dario usage` — focused burn-rate summary of the running proxy's
+ * traffic. Hits `/analytics` on the local proxy (default port 3456,
+ * overridable with --port=N or DARIO_USAGE_PORT) and prints a
+ * human-readable digest: requests in the last hour, token totals,
+ * subscription % vs. extra-usage, per-account rotation if pool mode
+ * is active.
+ *
+ * When the proxy isn't running on the expected port, prints a hint
+ * pointing at `dario doctor --usage` (which fires a Haiku rate-limit
+ * probe directly to Anthropic — different purpose, but the closest
+ * substitute when there's no live proxy traffic to summarize).
+ *
+ * --json mode emits the raw /analytics payload for machine consumption
+ * (CI dashboards, status bars, the MCP `usage` tool that wraps this).
+ */
+async function usage() {
+    const portArg = args.find(a => a.startsWith('--port='));
+    const port = portArg
+        ? parseInt(portArg.split('=')[1], 10)
+        : process.env['DARIO_USAGE_PORT']
+            ? parseInt(process.env['DARIO_USAGE_PORT'], 10)
+            : 3456;
+    const asJson = args.includes('--json');
+    const url = `http://127.0.0.1:${port}/analytics`;
+    let payload = null;
+    let connectError = null;
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+        if (!res.ok) {
+            connectError = `proxy responded ${res.status}`;
+        }
+        else {
+            payload = await res.json();
+        }
+    }
+    catch (err) {
+        connectError = err instanceof Error ? err.message : String(err);
+    }
+    if (asJson) {
+        if (payload) {
+            process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+            return;
+        }
+        process.stdout.write(JSON.stringify({ error: 'proxy not reachable', port, detail: connectError }, null, 2) + '\n');
+        process.exit(1);
+    }
+    console.log('');
+    console.log('  dario — Usage');
+    console.log('  ─────────────');
+    console.log('');
+    if (!payload) {
+        console.log(`  Proxy not reachable on http://127.0.0.1:${port} (${connectError ?? 'no response'}).`);
+        console.log('  `dario usage` summarizes traffic from a running proxy (live history).');
+        console.log('  For a one-off rate-limit snapshot from Anthropic, run:');
+        console.log('');
+        console.log('    dario doctor --usage');
+        console.log('');
+        console.log('  Costs ~1 subscription request; works without a running proxy.');
+        console.log('');
+        process.exit(1);
+    }
+    // Pool mode response shape:
+    //   { window: { minutes, requests, ...stats }, allTime: {...},
+    //     perAccount, perModel, utilization, predictions }
+    // Single-account mode response shape:
+    //   { mode: 'single-account', note: '...' }
+    if (payload.mode === 'single-account') {
+        console.log('  Mode:    single-account');
+        console.log('');
+        console.log(`  ${payload.note}`);
+        console.log('');
+        console.log('  For a live snapshot of your subscription rate limit, run:');
+        console.log('    dario doctor --usage');
+        console.log('');
+        return;
+    }
+    const win = payload.window;
+    const allTime = payload.allTime;
+    const perAccount = payload.perAccount;
+    console.log('  Mode:    pool');
+    console.log(`  Window:  last ${win?.minutes ?? 60} minutes`);
+    console.log('');
+    console.log(`  Requests:        ${win?.requests ?? 0}` + (allTime ? `  (all-time: ${allTime.requests ?? 0})` : ''));
+    if (win && win.requests > 0) {
+        console.log(`  Input tokens:    ${(win.totalInputTokens ?? 0).toLocaleString()}`);
+        console.log(`  Output tokens:   ${(win.totalOutputTokens ?? 0).toLocaleString()}`);
+        console.log(`  Avg latency:     ${win.avgLatencyMs ?? 0} ms`);
+        if ((win.errorRate ?? 0) > 0) {
+            console.log(`  Error rate:      ${((win.errorRate ?? 0) * 100).toFixed(1)}%`);
+        }
+        console.log(`  Subscription %:  ${win.subscriptionPercent ?? 0}%`);
+        if ((win.estimatedCost ?? 0) > 0) {
+            console.log(`  Est. cost:       $${(win.estimatedCost ?? 0).toFixed(4)} (would-be API cost)`);
+        }
+    }
+    if (perAccount && Object.keys(perAccount).length > 0) {
+        console.log('');
+        console.log('  Per-account:');
+        const aliasWidth = Math.max(...Object.keys(perAccount).map((a) => a.length));
+        for (const [alias, stats] of Object.entries(perAccount)) {
+            console.log(`    ${alias.padEnd(aliasWidth)}  ${stats.requests} req${stats.requests === 1 ? '' : 's'}  (${stats.subscriptionPercent}% subscription)`);
+        }
+    }
+    console.log('');
+}
 // Main
 const commands = {
     login,
@@ -1148,6 +1413,7 @@ const commands = {
     doctor,
     config,
     upgrade,
+    usage,
     help,
     version,
     '--help': help,