Merge branch 'main' into commands-list-clean

2026-01-09 11:46:08 -05:00
parent 4658f937cc f146c9ef16
commit 401f2a77e3
26 changed files with 913 additions and 364 deletions
--- a/src/agents/system-prompt.ts
+++ b/src/agents/system-prompt.ts
@@ -222,6 +222,7 @@ export function buildAgentSystemPrompt(params: {
    "To request a native reply/quote on supported surfaces, include one tag in your reply:",
    "- [[reply_to_current]] replies to the triggering message.",
    "- [[reply_to:<id>]] replies to a specific message id when you have it.",
+    "Whitespace inside the tag is allowed (e.g. [[ reply_to_current ]] / [[ reply_to: 123 ]]).",
    "Tags are stripped before sending; support depends on the current provider config.",
    "",
    "## Messaging",
--- a/src/auto-reply/command-detection.test.ts
+++ b/src/auto-reply/command-detection.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { hasControlCommand } from "./command-detection.js";
+import { listChatCommands } from "./commands-registry.js";
 import { parseActivationCommand } from "./group-activation.js";
 import { parseSendPolicyCommand } from "./send-policy.js";

@@ -37,17 +38,20 @@ describe("control command parsing", () => {
  });

  it("treats bare commands as non-control", () => {
-    expect(hasControlCommand("/send")).toBe(true);
    expect(hasControlCommand("send")).toBe(false);
-    expect(hasControlCommand("/help")).toBe(true);
-    expect(hasControlCommand("/help:")).toBe(true);
    expect(hasControlCommand("help")).toBe(false);
    expect(hasControlCommand("/commands")).toBe(true);
    expect(hasControlCommand("/commands:")).toBe(true);
    expect(hasControlCommand("commands")).toBe(false);
-    expect(hasControlCommand("/status")).toBe(true);
-    expect(hasControlCommand("/status:")).toBe(true);
    expect(hasControlCommand("status")).toBe(false);
+    expect(hasControlCommand("usage")).toBe(false);
+
+    for (const command of listChatCommands()) {
+      for (const alias of command.textAliases) {
+        expect(hasControlCommand(alias)).toBe(true);
+        expect(hasControlCommand(`${alias}:`)).toBe(true);
+      }
+    }
  });

  it("requires commands to be the full message", () => {
--- a/src/auto-reply/commands-registry.test.ts
+++ b/src/auto-reply/commands-registry.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import {
  buildCommandText,
  getCommandDetection,
+  listChatCommands,
  listNativeCommandSpecs,
  shouldHandleTextCommands,
 } from "./commands-registry.js";
@@ -21,15 +22,21 @@ describe("commands registry", () => {

  it("detects known text commands", () => {
    const detection = getCommandDetection();
-    expect(detection.exact.has("/help")).toBe(true);
-    expect(detection.exact.has("/commands")).toBe(true);
-    expect(detection.regex.test("/status")).toBe(true);
-    expect(detection.regex.test("/status:")).toBe(true);
-    expect(detection.regex.test("/stop")).toBe(true);
-    expect(detection.regex.test("/send:")).toBe(true);
-    expect(detection.regex.test("/debug set foo=bar")).toBe(true);
-    expect(detection.regex.test("/models")).toBe(true);
-    expect(detection.regex.test("/models list")).toBe(true);
+    for (const command of listChatCommands()) {
+      for (const alias of command.textAliases) {
+        expect(detection.exact.has(alias.toLowerCase())).toBe(true);
+        expect(detection.regex.test(alias)).toBe(true);
+        expect(detection.regex.test(`${alias}:`)).toBe(true);
+
+        if (command.acceptsArgs) {
+          expect(detection.regex.test(`${alias} list`)).toBe(true);
+          expect(detection.regex.test(`${alias}: list`)).toBe(true);
+        } else {
+          expect(detection.regex.test(`${alias} list`)).toBe(false);
+          expect(detection.regex.test(`${alias}: list`)).toBe(false);
+        }
+      }
+    }
    expect(detection.regex.test("try /status")).toBe(false);
  });

--- a/src/auto-reply/commands-registry.ts
+++ b/src/auto-reply/commands-registry.ts
@@ -14,123 +14,186 @@ export type NativeCommandSpec = {
  acceptsArgs: boolean;
 };

-const CHAT_COMMANDS: ChatCommandDefinition[] = [
-  {
-    key: "help",
-    nativeName: "help",
-    description: "Show available commands.",
-    textAliases: ["/help"],
-  },
-  {
-    key: "commands",
-    nativeName: "commands",
-    description: "List all slash commands.",
-    textAliases: ["/commands"],
-  },
-  {
-    key: "status",
-    nativeName: "status",
-    description: "Show current status.",
-    textAliases: ["/status"],
-  },
-  {
-    key: "debug",
-    nativeName: "debug",
-    description: "Set runtime debug overrides.",
-    textAliases: ["/debug"],
-    acceptsArgs: true,
-  },
-  {
-    key: "cost",
-    nativeName: "cost",
-    description: "Toggle per-response usage line.",
-    textAliases: ["/cost"],
-    acceptsArgs: true,
-  },
-  {
-    key: "stop",
-    nativeName: "stop",
-    description: "Stop the current run.",
-    textAliases: ["/stop"],
-  },
-  {
-    key: "restart",
-    nativeName: "restart",
-    description: "Restart Clawdbot.",
-    textAliases: ["/restart"],
-  },
-  {
-    key: "activation",
-    nativeName: "activation",
-    description: "Set group activation mode.",
-    textAliases: ["/activation"],
-    acceptsArgs: true,
-  },
-  {
-    key: "send",
-    nativeName: "send",
-    description: "Set send policy.",
-    textAliases: ["/send"],
-    acceptsArgs: true,
-  },
-  {
-    key: "reset",
-    nativeName: "reset",
-    description: "Reset the current session.",
-    textAliases: ["/reset"],
-  },
-  {
-    key: "new",
-    nativeName: "new",
-    description: "Start a new session.",
-    textAliases: ["/new"],
-  },
-  {
-    key: "think",
-    nativeName: "think",
-    description: "Set thinking level.",
-    textAliases: ["/thinking", "/think", "/t"],
-    acceptsArgs: true,
-  },
-  {
-    key: "verbose",
-    nativeName: "verbose",
-    description: "Toggle verbose mode.",
-    textAliases: ["/verbose", "/v"],
-    acceptsArgs: true,
-  },
-  {
-    key: "reasoning",
-    nativeName: "reasoning",
-    description: "Toggle reasoning visibility.",
-    textAliases: ["/reasoning", "/reason"],
-    acceptsArgs: true,
-  },
-  {
-    key: "elevated",
-    nativeName: "elevated",
-    description: "Toggle elevated mode.",
-    textAliases: ["/elevated", "/elev"],
-    acceptsArgs: true,
-  },
-  {
-    key: "model",
-    nativeName: "model",
-    description: "Show or set the model.",
-    textAliases: ["/model", "/models"],
-    acceptsArgs: true,
-  },
-  {
-    key: "queue",
-    nativeName: "queue",
-    description: "Adjust queue settings.",
-    textAliases: ["/queue"],
-    acceptsArgs: true,
-  },
-];
+function defineChatCommand(
+  command: Omit<ChatCommandDefinition, "textAliases"> & { textAlias: string },
+): ChatCommandDefinition {
+  return {
+    key: command.key,
+    nativeName: command.nativeName,
+    description: command.description,
+    acceptsArgs: command.acceptsArgs,
+    textAliases: [command.textAlias],
+  };
+}
+
+function registerAlias(
+  commands: ChatCommandDefinition[],
+  key: string,
+  ...aliases: string[]
+): void {
+  const command = commands.find((entry) => entry.key === key);
+  if (!command) {
+    throw new Error(`registerAlias: unknown command key: ${key}`);
+  }
+  const existing = new Set(command.textAliases.map((alias) => alias.trim()));
+  for (const alias of aliases) {
+    const trimmed = alias.trim();
+    if (!trimmed) continue;
+    if (existing.has(trimmed)) continue;
+    existing.add(trimmed);
+    command.textAliases.push(trimmed);
+  }
+}
+
+export const CHAT_COMMANDS: ChatCommandDefinition[] = (() => {
+  const commands: ChatCommandDefinition[] = [
+    defineChatCommand({
+      key: "help",
+      nativeName: "help",
+      description: "Show available commands.",
+      textAlias: "/help",
+    }),
+    defineChatCommand({
+      key: "commands",
+      nativeName: "commands",
+      description: "List all slash commands.",
+      textAlias: "/commands",
+    }),
+    defineChatCommand({
+      key: "status",
+      nativeName: "status",
+      description: "Show current status.",
+      textAlias: "/status",
+    }),
+    defineChatCommand({
+      key: "debug",
+      nativeName: "debug",
+      description: "Set runtime debug overrides.",
+      textAlias: "/debug",
+      acceptsArgs: true,
+    }),
+    defineChatCommand({
+      key: "cost",
+      nativeName: "cost",
+      description: "Toggle per-response usage line.",
+      textAlias: "/cost",
+      acceptsArgs: true,
+    }),
+    defineChatCommand({
+      key: "stop",
+      nativeName: "stop",
+      description: "Stop the current run.",
+      textAlias: "/stop",
+    }),
+    defineChatCommand({
+      key: "restart",
+      nativeName: "restart",
+      description: "Restart Clawdbot.",
+      textAlias: "/restart",
+    }),
+    defineChatCommand({
+      key: "activation",
+      nativeName: "activation",
+      description: "Set group activation mode.",
+      textAlias: "/activation",
+      acceptsArgs: true,
+    }),
+    defineChatCommand({
+      key: "send",
+      nativeName: "send",
+      description: "Set send policy.",
+      textAlias: "/send",
+      acceptsArgs: true,
+    }),
+    defineChatCommand({
+      key: "reset",
+      nativeName: "reset",
+      description: "Reset the current session.",
+      textAlias: "/reset",
+    }),
+    defineChatCommand({
+      key: "new",
+      nativeName: "new",
+      description: "Start a new session.",
+      textAlias: "/new",
+    }),
+    defineChatCommand({
+      key: "think",
+      nativeName: "think",
+      description: "Set thinking level.",
+      textAlias: "/think",
+      acceptsArgs: true,
+    }),
+    defineChatCommand({
+      key: "verbose",
+      nativeName: "verbose",
+      description: "Toggle verbose mode.",
+      textAlias: "/verbose",
+      acceptsArgs: true,
+    }),
+    defineChatCommand({
+      key: "reasoning",
+      nativeName: "reasoning",
+      description: "Toggle reasoning visibility.",
+      textAlias: "/reasoning",
+      acceptsArgs: true,
+    }),
+    defineChatCommand({
+      key: "elevated",
+      nativeName: "elevated",
+      description: "Toggle elevated mode.",
+      textAlias: "/elevated",
+      acceptsArgs: true,
+    }),
+    defineChatCommand({
+      key: "model",
+      nativeName: "model",
+      description: "Show or set the model.",
+      textAlias: "/model",
+      acceptsArgs: true,
+    }),
+    defineChatCommand({
+      key: "queue",
+      nativeName: "queue",
+      description: "Adjust queue settings.",
+      textAlias: "/queue",
+      acceptsArgs: true,
+    }),
+  ];
+
+  registerAlias(commands, "status", "/usage");
+  registerAlias(commands, "think", "/thinking", "/t");
+  registerAlias(commands, "verbose", "/v");
+  registerAlias(commands, "reasoning", "/reason");
+  registerAlias(commands, "elevated", "/elev");
+  registerAlias(commands, "model", "/models");
+
+  return commands;
+})();

 const NATIVE_COMMAND_SURFACES = new Set(["discord", "slack", "telegram"]);

+type TextAliasSpec = {
+  canonical: string;
+  acceptsArgs: boolean;
+};
+
+const TEXT_ALIAS_MAP: Map<string, TextAliasSpec> = (() => {
+  const map = new Map<string, TextAliasSpec>();
+  for (const command of CHAT_COMMANDS) {
+    const canonical = `/${command.key}`;
+    const acceptsArgs = Boolean(command.acceptsArgs);
+    for (const alias of command.textAliases) {
+      const normalized = alias.trim().toLowerCase();
+      if (!normalized) continue;
+      if (!map.has(normalized)) {
+        map.set(normalized, { canonical, acceptsArgs });
+      }
+    }
+  }
+  return map;
+})();
+
 let cachedDetection:
  | {
      exact: Set<string>;
@@ -171,11 +234,31 @@ export function buildCommandText(commandName: string, args?: string): string {
 export function normalizeCommandBody(raw: string): string {
  const trimmed = raw.trim();
  if (!trimmed.startsWith("/")) return trimmed;
-  const match = trimmed.match(/^\/([^\s:]+)\s*:(.*)$/);
-  if (!match) return trimmed;
-  const [, command, rest] = match;
-  const normalizedRest = rest.trimStart();
-  return normalizedRest ? `/${command} ${normalizedRest}` : `/${command}`;
+
+  const colonMatch = trimmed.match(/^\/([^\s:]+)\s*:(.*)$/);
+  const normalized = colonMatch
+    ? (() => {
+        const [, command, rest] = colonMatch;
+        const normalizedRest = rest.trimStart();
+        return normalizedRest ? `/${command} ${normalizedRest}` : `/${command}`;
+      })()
+    : trimmed;
+
+  const lowered = normalized.toLowerCase();
+  const exact = TEXT_ALIAS_MAP.get(lowered);
+  if (exact) return exact.canonical;
+
+  const tokenMatch = normalized.match(/^\/([^\s]+)(?:\s+([\s\S]+))?$/);
+  if (!tokenMatch) return normalized;
+  const [, token, rest] = tokenMatch;
+  const tokenKey = `/${token.toLowerCase()}`;
+  const tokenSpec = TEXT_ALIAS_MAP.get(tokenKey);
+  if (!tokenSpec) return normalized;
+  if (rest && !tokenSpec.acceptsArgs) return normalized;
+  const normalizedRest = rest?.trimStart();
+  return normalizedRest
+    ? `${tokenSpec.canonical} ${normalizedRest}`
+    : tokenSpec.canonical;
 }

 export function getCommandDetection(): { exact: Set<string>; regex: RegExp } {
--- a/src/auto-reply/reply.directive.parse.test.ts
+++ b/src/auto-reply/reply.directive.parse.test.ts
@@ -144,6 +144,12 @@ describe("directive parsing", () => {
    expect(res.cleaned).toBe("thats not /tmp/hello");
  });

+  it("preserves spacing when stripping usage directives before paths", () => {
+    const res = extractStatusDirective("thats not /usage:/tmp/hello");
+    expect(res.hasDirective).toBe(true);
+    expect(res.cleaned).toBe("thats not /tmp/hello");
+  });
+
  it("parses queue options and modes", () => {
    const res = extractQueueDirective(
      "please /queue steer+backlog debounce:2s cap:5 drop:summarize now",
--- a/src/auto-reply/reply.directive.test.ts
+++ b/src/auto-reply/reply.directive.test.ts
@@ -249,6 +249,42 @@ describe("directive behavior", () => {
    });
  });

+  it("strips reply tags with whitespace and maps reply_to_current to MessageSid", async () => {
+    await withTempHome(async (home) => {
+      vi.mocked(runEmbeddedPiAgent).mockResolvedValue({
+        payloads: [{ text: "hello [[ reply_to_current ]]" }],
+        meta: {
+          durationMs: 5,
+          agentMeta: { sessionId: "s", provider: "p", model: "m" },
+        },
+      });
+
+      const res = await getReplyFromConfig(
+        {
+          Body: "ping",
+          From: "+1004",
+          To: "+2000",
+          MessageSid: "msg-123",
+        },
+        {},
+        {
+          agents: {
+            defaults: {
+              model: "anthropic/claude-opus-4-5",
+              workspace: path.join(home, "clawd"),
+            },
+          },
+          whatsapp: { allowFrom: ["*"] },
+          session: { store: path.join(home, "sessions.json") },
+        },
+      );
+
+      const payload = Array.isArray(res) ? res[0] : res;
+      expect(payload?.text).toBe("hello");
+      expect(payload?.replyToId).toBe("msg-123");
+    });
+  });
+
  it("prefers explicit reply_to id over reply_to_current", async () => {
    await withTempHome(async (home) => {
      vi.mocked(runEmbeddedPiAgent).mockResolvedValue({
--- a/src/auto-reply/reply.triggers.test.ts
+++ b/src/auto-reply/reply.triggers.test.ts
@@ -242,6 +242,23 @@ describe("trigger handling", () => {
    });
  });

+  it("reports status via /usage without invoking the agent", async () => {
+    await withTempHome(async (home) => {
+      const res = await getReplyFromConfig(
+        {
+          Body: "/usage",
+          From: "+1002",
+          To: "+2000",
+        },
+        {},
+        makeCfg(home),
+      );
+      const text = Array.isArray(res) ? res[0]?.text : res?.text;
+      expect(text).toContain("ClawdBot");
+      expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
+    });
+  });
+
  it("reports active auth profile and key snippet in status", async () => {
    await withTempHome(async (home) => {
      const cfg = makeCfg(home);
@@ -1240,6 +1257,7 @@ describe("trigger handling", () => {
        vi.mocked(runEmbeddedPiAgent).mock.calls[0]?.[0]?.prompt ?? "";
      expect(prompt).toContain("Give me the status");
      expect(prompt).not.toContain("/thinking high");
+      expect(prompt).not.toContain("/think high");
    });
  });

--- a/src/auto-reply/reply/directives.ts
+++ b/src/auto-reply/reply/directives.ts
@@ -170,7 +170,7 @@ export function extractStatusDirective(body?: string): {
  hasDirective: boolean;
 } {
  if (!body) return { cleaned: "", hasDirective: false };
-  return extractSimpleDirective(body, ["status"]);
+  return extractSimpleDirective(body, ["status", "usage"]);
 }

 export type { ElevatedLevel, ReasoningLevel, ThinkLevel, VerboseLevel };
--- a/src/auto-reply/reply/reply-tags.ts
+++ b/src/auto-reply/reply/reply-tags.ts
@@ -1,3 +1,13 @@
+const REPLY_TAG_RE =
+  /\[\[\s*(?:reply_to_current|reply_to\s*:\s*([^\]\n]+))\s*\]\]/gi;
+
+function normalizeReplyText(text: string) {
+  return text
+    .replace(/[ \t]+/g, " ")
+    .replace(/[ \t]*\n[ \t]*/g, "\n")
+    .trim();
+}
+
 export function extractReplyToTag(
  text?: string,
  currentMessageId?: string,
@@ -7,29 +17,28 @@ export function extractReplyToTag(
  hasTag: boolean;
 } {
  if (!text) return { cleaned: "", hasTag: false };
-  let cleaned = text;
-  let replyToId: string | undefined;
+
+  let sawCurrent = false;
+  let lastExplicitId: string | undefined;
  let hasTag = false;

-  const currentMatch = cleaned.match(/\[\[\s*reply_to_current\s*\]\]/i);
-  if (currentMatch) {
-    cleaned = cleaned.replace(/\[\[\s*reply_to_current\s*\]\]/gi, " ");
-    hasTag = true;
-    if (currentMessageId?.trim()) {
-      replyToId = currentMessageId.trim();
-    }
-  }
+  const cleaned = normalizeReplyText(
+    text.replace(REPLY_TAG_RE, (_full, idRaw: string | undefined) => {
+      hasTag = true;
+      if (idRaw === undefined) {
+        sawCurrent = true;
+        return " ";
+      }

-  const idMatch = cleaned.match(/\[\[\s*reply_to\s*:\s*([^\]\n]+)\s*\]\]/i);
-  if (idMatch?.[1]) {
-    cleaned = cleaned.replace(/\[\[\s*reply_to\s*:\s*[^\]\n]+\s*\]\]/gi, " ");
-    replyToId = idMatch[1].trim();
-    hasTag = true;
-  }
+      const id = idRaw.trim();
+      if (id) lastExplicitId = id;
+      return " ";
+    }),
+  );
+
+  const replyToId =
+    lastExplicitId ??
+    (sawCurrent ? currentMessageId?.trim() || undefined : undefined);

-  cleaned = cleaned
-    .replace(/[ \t]+/g, " ")
-    .replace(/[ \t]*\n[ \t]*/g, "\n")
-    .trim();
  return { cleaned, replyToId, hasTag };
 }
--- a/src/discord/monitor.tool-result.test.ts
+++ b/src/discord/monitor.tool-result.test.ts
@@ -1,5 +1,6 @@
 import type { Client } from "@buape/carbon";
 import { ChannelType, MessageType } from "@buape/carbon";
+import { Routes } from "discord-api-types/v10";
 import { beforeEach, describe, expect, it, vi } from "vitest";

 const sendMock = vi.fn();
@@ -119,6 +120,79 @@ describe("discord tool result dispatch", () => {
    expect(sendMock.mock.calls[0]?.[1]).toMatch(/^PFX /);
  }, 10000);

+  it("caches channel info lookups between messages", async () => {
+    const { createDiscordMessageHandler } = await import("./monitor.js");
+    const cfg = {
+      agents: {
+        defaults: {
+          model: "anthropic/claude-opus-4-5",
+          workspace: "/tmp/clawd",
+        },
+      },
+      session: { store: "/tmp/clawdbot-sessions.json" },
+      discord: { dm: { enabled: true, policy: "open" } },
+    } as ReturnType<typeof import("../config/config.js").loadConfig>;
+
+    const handler = createDiscordMessageHandler({
+      cfg,
+      discordConfig: cfg.discord,
+      accountId: "default",
+      token: "token",
+      runtime: {
+        log: vi.fn(),
+        error: vi.fn(),
+        exit: (code: number): never => {
+          throw new Error(`exit ${code}`);
+        },
+      },
+      botUserId: "bot-id",
+      guildHistories: new Map(),
+      historyLimit: 0,
+      mediaMaxBytes: 10_000,
+      textLimit: 2000,
+      replyToMode: "off",
+      dmEnabled: true,
+      groupDmEnabled: false,
+    });
+
+    const fetchChannel = vi.fn().mockResolvedValue({
+      type: ChannelType.DM,
+      name: "dm",
+    });
+    const client = { fetchChannel } as unknown as Client;
+    const baseMessage = {
+      content: "hello",
+      channelId: "cache-channel-1",
+      timestamp: new Date().toISOString(),
+      type: MessageType.Default,
+      attachments: [],
+      embeds: [],
+      mentionedEveryone: false,
+      mentionedUsers: [],
+      mentionedRoles: [],
+      author: { id: "u-cache", bot: false, username: "Ada" },
+    };
+
+    await handler(
+      {
+        message: { ...baseMessage, id: "m-cache-1" },
+        author: baseMessage.author,
+        guild_id: null,
+      },
+      client,
+    );
+    await handler(
+      {
+        message: { ...baseMessage, id: "m-cache-2" },
+        author: baseMessage.author,
+        guild_id: null,
+      },
+      client,
+    );
+
+    expect(fetchChannel).toHaveBeenCalledTimes(1);
+  });
+
  it("replies with pairing code and sender id when dmPolicy is pairing", async () => {
    const { createDiscordMessageHandler } = await import("./monitor.js");
    const cfg = {
@@ -381,6 +455,110 @@ describe("discord tool result dispatch", () => {
    expect(capturedCtx?.ThreadLabel).toContain("Discord thread #general");
  });

+  it("treats forum threads as distinct sessions without channel payloads", async () => {
+    const { createDiscordMessageHandler } = await import("./monitor.js");
+    let capturedCtx:
+      | {
+          SessionKey?: string;
+          ParentSessionKey?: string;
+          ThreadStarterBody?: string;
+          ThreadLabel?: string;
+        }
+      | undefined;
+    dispatchMock.mockImplementationOnce(async ({ ctx, dispatcher }) => {
+      capturedCtx = ctx;
+      dispatcher.sendFinalReply({ text: "hi" });
+      return { queuedFinal: true, counts: { final: 1 } };
+    });
+
+    const cfg = {
+      agent: { model: "anthropic/claude-opus-4-5", workspace: "/tmp/clawd" },
+      session: { store: "/tmp/clawdbot-sessions.json" },
+      discord: {
+        dm: { enabled: true, policy: "open" },
+        guilds: { "*": { requireMention: false } },
+      },
+      routing: { allowFrom: [] },
+    } as ReturnType<typeof import("../config/config.js").loadConfig>;
+
+    const handler = createDiscordMessageHandler({
+      cfg,
+      discordConfig: cfg.discord,
+      accountId: "default",
+      token: "token",
+      runtime: {
+        log: vi.fn(),
+        error: vi.fn(),
+        exit: (code: number): never => {
+          throw new Error(`exit ${code}`);
+        },
+      },
+      botUserId: "bot-id",
+      guildHistories: new Map(),
+      historyLimit: 0,
+      mediaMaxBytes: 10_000,
+      textLimit: 2000,
+      replyToMode: "off",
+      dmEnabled: true,
+      groupDmEnabled: false,
+      guildEntries: { "*": { requireMention: false } },
+    });
+
+    const fetchChannel = vi
+      .fn()
+      .mockResolvedValueOnce({
+        type: ChannelType.PublicThread,
+        name: "topic-1",
+        parentId: "forum-1",
+      })
+      .mockResolvedValueOnce({
+        type: ChannelType.GuildForum,
+        name: "support",
+      });
+    const restGet = vi.fn().mockResolvedValue({
+      content: "starter message",
+      author: { id: "u1", username: "Alice", discriminator: "0001" },
+      timestamp: new Date().toISOString(),
+    });
+    const client = {
+      fetchChannel,
+      rest: {
+        get: restGet,
+      },
+    } as unknown as Client;
+
+    await handler(
+      {
+        message: {
+          id: "m6",
+          content: "thread reply",
+          channelId: "t1",
+          timestamp: new Date().toISOString(),
+          type: MessageType.Default,
+          attachments: [],
+          embeds: [],
+          mentionedEveryone: false,
+          mentionedUsers: [],
+          mentionedRoles: [],
+          author: { id: "u2", bot: false, username: "Bob", tag: "Bob#2" },
+        },
+        author: { id: "u2", bot: false, username: "Bob", tag: "Bob#2" },
+        member: { displayName: "Bob" },
+        guild: { id: "g1", name: "Guild" },
+        guild_id: "g1",
+      },
+      client,
+    );
+
+    expect(capturedCtx?.SessionKey).toBe("agent:main:discord:channel:t1");
+    expect(capturedCtx?.ParentSessionKey).toBe(
+      "agent:main:discord:channel:forum-1",
+    );
+    expect(capturedCtx?.ThreadStarterBody).toContain("starter message");
+    expect(capturedCtx?.ThreadLabel).toContain("Discord thread #support");
+    expect(restGet).toHaveBeenCalledWith(Routes.channelMessage("t1", "t1"));
+  });
+
  it("scopes thread sessions to the routed agent", async () => {
    const { createDiscordMessageHandler } = await import("./monitor.js");

--- a/src/discord/monitor.ts
+++ b/src/discord/monitor.ts
@@ -113,7 +113,20 @@ type DiscordThreadStarter = {
  timestamp?: number;
 };

+type DiscordChannelInfo = {
+  type: ChannelType;
+  name?: string;
+  topic?: string;
+  parentId?: string;
+};
+
 const DISCORD_THREAD_STARTER_CACHE = new Map<string, DiscordThreadStarter>();
+const DISCORD_CHANNEL_INFO_CACHE_TTL_MS = 5 * 60 * 1000;
+const DISCORD_CHANNEL_INFO_NEGATIVE_CACHE_TTL_MS = 30 * 1000;
+const DISCORD_CHANNEL_INFO_CACHE = new Map<
+  string,
+  { value: DiscordChannelInfo | null; expiresAt: number }
+>();
 const DISCORD_SLOW_LISTENER_THRESHOLD_MS = 1000;

 function logSlowDiscordListener(params: {
@@ -139,14 +152,22 @@ async function resolveDiscordThreadStarter(params: {
  channel: DiscordThreadChannel;
  client: Client;
  parentId?: string;
+  parentType?: ChannelType;
 }): Promise<DiscordThreadStarter | null> {
  const cacheKey = params.channel.id;
  const cached = DISCORD_THREAD_STARTER_CACHE.get(cacheKey);
  if (cached) return cached;
  try {
-    if (!params.parentId) return null;
+    const parentType = params.parentType;
+    const isForumParent =
+      parentType === ChannelType.GuildForum ||
+      parentType === ChannelType.GuildMedia;
+    const messageChannelId = isForumParent
+      ? params.channel.id
+      : params.parentId;
+    if (!messageChannelId) return null;
    const starter = (await params.client.rest.get(
-      Routes.channelMessage(params.parentId, params.channel.id),
+      Routes.channelMessage(messageChannelId, params.channel.id),
    )) as {
      content?: string | null;
      embeds?: Array<{ description?: string | null }>;
@@ -226,6 +247,14 @@ export type DiscordMessageHandler = (
  client: Client,
 ) => Promise<void>;

+function isDiscordThreadType(type: ChannelType | undefined): boolean {
+  return (
+    type === ChannelType.PublicThread ||
+    type === ChannelType.PrivateThread ||
+    type === ChannelType.AnnouncementThread
+  );
+}
+
 export function resolveDiscordReplyTarget(opts: {
  replyToMode: ReplyToMode;
  replyToId?: string;
@@ -666,12 +695,33 @@ export function createDiscordMessageHandler(params: {
        message.channel &&
        "isThread" in message.channel &&
        message.channel.isThread();
-      const threadChannel = isThreadChannel
+      const isThreadByType =
+        isGuildMessage && isDiscordThreadType(channelInfo?.type);
+      const threadChannel: DiscordThreadChannel | null = isThreadChannel
        ? (message.channel as DiscordThreadChannel)
-        : null;
+        : isThreadByType
+          ? {
+              id: message.channelId,
+              name: channelInfo?.name ?? undefined,
+              parentId: channelInfo?.parentId ?? undefined,
+              parent: undefined,
+            }
+          : null;
      const threadParentId =
-        threadChannel?.parentId ?? threadChannel?.parent?.id ?? undefined;
-      const threadParentName = threadChannel?.parent?.name;
+        threadChannel?.parentId ??
+        threadChannel?.parent?.id ??
+        channelInfo?.parentId ??
+        undefined;
+      let threadParentName = threadChannel?.parent?.name;
+      let threadParentType: ChannelType | undefined;
+      if (threadChannel && threadParentId) {
+        const parentInfo = await resolveDiscordChannelInfo(
+          client,
+          threadParentId,
+        );
+        threadParentName = threadParentName ?? parentInfo?.name;
+        threadParentType = parentInfo?.type;
+      }
      const threadName = threadChannel?.name;
      const configChannelName = threadParentName ?? channelName;
      const configChannelSlug = configChannelName
@@ -935,6 +985,7 @@ export function createDiscordMessageHandler(params: {
          channel: threadChannel,
          client,
          parentId: threadParentId,
+          parentType: threadParentType,
        });
        if (starter?.text) {
          const starterEnvelope = formatThreadStarterEnvelope({
@@ -1684,15 +1735,42 @@ async function deliverDiscordReply(params: {
 async function resolveDiscordChannelInfo(
  client: Client,
  channelId: string,
-): Promise<{ type: ChannelType; name?: string; topic?: string } | null> {
+): Promise<DiscordChannelInfo | null> {
+  const cached = DISCORD_CHANNEL_INFO_CACHE.get(channelId);
+  if (cached) {
+    if (cached.expiresAt > Date.now()) return cached.value;
+    DISCORD_CHANNEL_INFO_CACHE.delete(channelId);
+  }
  try {
    const channel = await client.fetchChannel(channelId);
-    if (!channel) return null;
+    if (!channel) {
+      DISCORD_CHANNEL_INFO_CACHE.set(channelId, {
+        value: null,
+        expiresAt: Date.now() + DISCORD_CHANNEL_INFO_NEGATIVE_CACHE_TTL_MS,
+      });
+      return null;
+    }
    const name = "name" in channel ? (channel.name ?? undefined) : undefined;
    const topic = "topic" in channel ? (channel.topic ?? undefined) : undefined;
-    return { type: channel.type, name, topic };
+    const parentId =
+      "parentId" in channel ? (channel.parentId ?? undefined) : undefined;
+    const payload: DiscordChannelInfo = {
+      type: channel.type,
+      name,
+      topic,
+      parentId,
+    };
+    DISCORD_CHANNEL_INFO_CACHE.set(channelId, {
+      value: payload,
+      expiresAt: Date.now() + DISCORD_CHANNEL_INFO_CACHE_TTL_MS,
+    });
+    return payload;
  } catch (err) {
    logVerbose(`discord: failed to fetch channel ${channelId}: ${String(err)}`);
+    DISCORD_CHANNEL_INFO_CACHE.set(channelId, {
+      value: null,
+      expiresAt: Date.now() + DISCORD_CHANNEL_INFO_NEGATIVE_CACHE_TTL_MS,
+    });
    return null;
  }
 }
--- a/src/docs/slash-commands-doc.test.ts
+++ b/src/docs/slash-commands-doc.test.ts
@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { listChatCommands } from "../auto-reply/commands-registry.js";
+
+function extractDocumentedSlashCommands(markdown: string): Set<string> {
+  const documented = new Set<string>();
+  for (const match of markdown.matchAll(/`\/(?!<)([a-z0-9_-]+)/gi)) {
+    documented.add(`/${match[1]}`);
+  }
+  return documented;
+}
+
+describe("slash commands docs", () => {
+  it("documents all built-in chat command aliases", async () => {
+    const docPath = path.join(
+      process.cwd(),
+      "docs",
+      "tools",
+      "slash-commands.md",
+    );
+    const markdown = await fs.readFile(docPath, "utf8");
+    const documented = extractDocumentedSlashCommands(markdown);
+
+    for (const command of listChatCommands()) {
+      for (const alias of command.textAliases) {
+        expect(documented.has(alias)).toBe(true);
+      }
+    }
+  });
+});
--- a/src/gateway/hooks.test.ts
+++ b/src/gateway/hooks.test.ts
@@ -66,6 +66,16 @@ describe("gateway hooks helpers", () => {
      expect(ok.value.sessionKey).toBe("hook:fixed");
      expect(ok.value.provider).toBe("last");
      expect(ok.value.name).toBe("Hook");
+      expect(ok.value.deliver).toBe(true);
+    }
+
+    const explicitNoDeliver = normalizeAgentPayload(
+      { message: "hello", deliver: false },
+      { idFactory: () => "fixed" },
+    );
+    expect(explicitNoDeliver.ok).toBe(true);
+    if (explicitNoDeliver.ok) {
+      expect(explicitNoDeliver.value.deliver).toBe(false);
    }

    const imsg = normalizeAgentPayload(
--- a/src/gateway/hooks.ts
+++ b/src/gateway/hooks.ts
@@ -210,7 +210,7 @@ export function normalizeAgentPayload(
  if (modelRaw !== undefined && !model) {
    return { ok: false, error: "model required" };
  }
-  const deliver = payload.deliver === true;
+  const deliver = payload.deliver !== false;
  const thinkingRaw = payload.thinking;
  const thinking =
    typeof thinkingRaw === "string" && thinkingRaw.trim()
--- a/src/gateway/server-bridge.ts
+++ b/src/gateway/server-bridge.ts
@@ -80,6 +80,7 @@ import {
  type SessionsPatchResult,
 } from "./session-utils.js";
 import { applySessionsPatchToStore } from "./sessions-patch.js";
+import { resolveSessionKeyFromResolveParams } from "./sessions-resolve.js";
 import { formatForLog } from "./ws-log.js";

 export type BridgeHandlersContext = {
@@ -314,93 +315,20 @@ export function createBridgeHandlers(ctx: BridgeHandlersContext) {

          const p = params as SessionsResolveParams;
          const cfg = loadConfig();
-
-          const key = typeof p.key === "string" ? p.key.trim() : "";
-          const label = typeof p.label === "string" ? p.label.trim() : "";
-          const hasKey = key.length > 0;
-          const hasLabel = label.length > 0;
-          if (hasKey && hasLabel) {
+          const resolved = resolveSessionKeyFromResolveParams({ cfg, p });
+          if (!resolved.ok) {
            return {
              ok: false,
              error: {
-                code: ErrorCodes.INVALID_REQUEST,
-                message: "Provide either key or label (not both)",
-              },
-            };
-          }
-          if (!hasKey && !hasLabel) {
-            return {
-              ok: false,
-              error: {
-                code: ErrorCodes.INVALID_REQUEST,
-                message: "Either key or label is required",
-              },
-            };
-          }
-
-          if (hasKey) {
-            const target = resolveGatewaySessionStoreTarget({ cfg, key });
-            const store = loadSessionStore(target.storePath);
-            const existingKey = target.storeKeys.find(
-              (candidate) => store[candidate],
-            );
-            if (!existingKey) {
-              return {
-                ok: false,
-                error: {
-                  code: ErrorCodes.INVALID_REQUEST,
-                  message: `No session found: ${key}`,
-                },
-              };
-            }
-            return {
-              ok: true,
-              payloadJSON: JSON.stringify({
-                ok: true,
-                key: target.canonicalKey,
-              }),
-            };
-          }
-
-          const { storePath, store } = loadCombinedSessionStoreForGateway(cfg);
-          const list = listSessionsFromStore({
-            cfg,
-            storePath,
-            store,
-            opts: {
-              includeGlobal: p.includeGlobal === true,
-              includeUnknown: p.includeUnknown === true,
-              label,
-              agentId: p.agentId,
-              spawnedBy: p.spawnedBy,
-              limit: 2,
-            },
-          });
-          if (list.sessions.length === 0) {
-            return {
-              ok: false,
-              error: {
-                code: ErrorCodes.INVALID_REQUEST,
-                message: `No session found with label: ${label}`,
-              },
-            };
-          }
-          if (list.sessions.length > 1) {
-            const keys = list.sessions.map((s) => s.key).join(", ");
-            return {
-              ok: false,
-              error: {
-                code: ErrorCodes.INVALID_REQUEST,
-                message: `Multiple sessions found with label: ${label} (${keys})`,
+                code: resolved.error.code,
+                message: resolved.error.message,
+                details: resolved.error.details,
              },
            };
          }
          return {
            ok: true,
-            payloadJSON: JSON.stringify({
-              ok: true,
-              key: list.sessions[0]?.key,
-            }),
+            payloadJSON: JSON.stringify({ ok: true, key: resolved.key }),
          };
        }
        case "sessions.patch": {
--- a/src/gateway/server-http.ts
+++ b/src/gateway/server-http.ts
@@ -176,7 +176,7 @@ export function createHooksRequestHandler(
            name: mapped.action.name ?? "Hook",
            wakeMode: mapped.action.wakeMode,
            sessionKey: mapped.action.sessionKey ?? "",
-            deliver: mapped.action.deliver === true,
+            deliver: mapped.action.deliver !== false,
            provider: mapped.action.provider ?? "last",
            to: mapped.action.to,
            model: mapped.action.model,
--- a/src/gateway/server-methods/sessions.ts
+++ b/src/gateway/server-methods/sessions.ts
@@ -35,6 +35,7 @@ import {
  type SessionsPatchResult,
 } from "../session-utils.js";
 import { applySessionsPatchToStore } from "../sessions-patch.js";
+import { resolveSessionKeyFromResolveParams } from "../sessions-resolve.js";
 import type { GatewayRequestHandlers } from "./types.js";

 export const sessionsHandlers: GatewayRequestHandlers = {
@@ -76,106 +77,12 @@ export const sessionsHandlers: GatewayRequestHandlers = {
    const p = params as import("../protocol/index.js").SessionsResolveParams;
    const cfg = loadConfig();

-    const key = typeof p.key === "string" ? p.key.trim() : "";
-    const label = typeof p.label === "string" ? p.label.trim() : "";
-    const hasKey = key.length > 0;
-    const hasLabel = label.length > 0;
-    if (hasKey && hasLabel) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          "Provide either key or label (not both)",
-        ),
-      );
+    const resolved = resolveSessionKeyFromResolveParams({ cfg, p });
+    if (!resolved.ok) {
+      respond(false, undefined, resolved.error);
      return;
    }
-    if (!hasKey && !hasLabel) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          "Either key or label is required",
-        ),
-      );
-      return;
-    }
-
-    if (hasKey) {
-      if (!key) {
-        respond(
-          false,
-          undefined,
-          errorShape(ErrorCodes.INVALID_REQUEST, "key required"),
-        );
-        return;
-      }
-      const target = resolveGatewaySessionStoreTarget({ cfg, key });
-      const store = loadSessionStore(target.storePath);
-      const existingKey = target.storeKeys.find(
-        (candidate) => store[candidate],
-      );
-      if (!existingKey) {
-        respond(
-          false,
-          undefined,
-          errorShape(ErrorCodes.INVALID_REQUEST, `No session found: ${key}`),
-        );
-        return;
-      }
-      respond(true, { ok: true, key: target.canonicalKey }, undefined);
-      return;
-    }
-
-    if (!label) {
-      respond(
-        false,
-        undefined,
-        errorShape(ErrorCodes.INVALID_REQUEST, "label required"),
-      );
-      return;
-    }
-
-    const { storePath, store } = loadCombinedSessionStoreForGateway(cfg);
-    const list = listSessionsFromStore({
-      cfg,
-      storePath,
-      store,
-      opts: {
-        includeGlobal: p.includeGlobal === true,
-        includeUnknown: p.includeUnknown === true,
-        label,
-        agentId: p.agentId,
-        spawnedBy: p.spawnedBy,
-        limit: 2,
-      },
-    });
-    if (list.sessions.length === 0) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `No session found with label: ${label}`,
-        ),
-      );
-      return;
-    }
-    if (list.sessions.length > 1) {
-      const keys = list.sessions.map((s) => s.key).join(", ");
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `Multiple sessions found with label: ${label} (${keys})`,
-        ),
-      );
-      return;
-    }
-    respond(true, { ok: true, key: list.sessions[0]?.key }, undefined);
+    respond(true, { ok: true, key: resolved.key }, undefined);
  },
  "sessions.patch": async ({ params, respond, context }) => {
    if (!validateSessionsPatchParams(params)) {
--- a/src/gateway/sessions-resolve.ts
+++ b/src/gateway/sessions-resolve.ts
@@ -0,0 +1,107 @@
+import type { ClawdbotConfig } from "../config/config.js";
+import { loadSessionStore } from "../config/sessions.js";
+import { parseSessionLabel } from "../sessions/session-label.js";
+import {
+  ErrorCodes,
+  type ErrorShape,
+  errorShape,
+  type SessionsResolveParams,
+} from "./protocol/index.js";
+import {
+  listSessionsFromStore,
+  loadCombinedSessionStoreForGateway,
+  resolveGatewaySessionStoreTarget,
+} from "./session-utils.js";
+
+export type SessionsResolveResult =
+  | { ok: true; key: string }
+  | { ok: false; error: ErrorShape };
+
+export function resolveSessionKeyFromResolveParams(params: {
+  cfg: ClawdbotConfig;
+  p: SessionsResolveParams;
+}): SessionsResolveResult {
+  const { cfg, p } = params;
+
+  const key = typeof p.key === "string" ? p.key.trim() : "";
+  const hasKey = key.length > 0;
+  const hasLabel = typeof p.label === "string" && p.label.trim().length > 0;
+  if (hasKey && hasLabel) {
+    return {
+      ok: false,
+      error: errorShape(
+        ErrorCodes.INVALID_REQUEST,
+        "Provide either key or label (not both)",
+      ),
+    };
+  }
+  if (!hasKey && !hasLabel) {
+    return {
+      ok: false,
+      error: errorShape(
+        ErrorCodes.INVALID_REQUEST,
+        "Either key or label is required",
+      ),
+    };
+  }
+
+  if (hasKey) {
+    const target = resolveGatewaySessionStoreTarget({ cfg, key });
+    const store = loadSessionStore(target.storePath);
+    const existingKey = target.storeKeys.find((candidate) => store[candidate]);
+    if (!existingKey) {
+      return {
+        ok: false,
+        error: errorShape(
+          ErrorCodes.INVALID_REQUEST,
+          `No session found: ${key}`,
+        ),
+      };
+    }
+    return { ok: true, key: target.canonicalKey };
+  }
+
+  const parsedLabel = parseSessionLabel(p.label);
+  if (!parsedLabel.ok) {
+    return {
+      ok: false,
+      error: errorShape(ErrorCodes.INVALID_REQUEST, parsedLabel.error),
+    };
+  }
+
+  const { storePath, store } = loadCombinedSessionStoreForGateway(cfg);
+  const list = listSessionsFromStore({
+    cfg,
+    storePath,
+    store,
+    opts: {
+      includeGlobal: p.includeGlobal === true,
+      includeUnknown: p.includeUnknown === true,
+      label: parsedLabel.label,
+      agentId: p.agentId,
+      spawnedBy: p.spawnedBy,
+      limit: 2,
+    },
+  });
+  if (list.sessions.length === 0) {
+    return {
+      ok: false,
+      error: errorShape(
+        ErrorCodes.INVALID_REQUEST,
+        `No session found with label: ${parsedLabel.label}`,
+      ),
+    };
+  }
+  if (list.sessions.length > 1) {
+    const keys = list.sessions.map((s) => s.key).join(", ");
+    return {
+      ok: false,
+      error: errorShape(
+        ErrorCodes.INVALID_REQUEST,
+        `Multiple sessions found with label: ${parsedLabel.label} (${keys})`,
+      ),
+    };
+  }
+
+  return { ok: true, key: String(list.sessions[0]?.key ?? "") };
+}
--- a/src/infra/provider-usage.test.ts
+++ b/src/infra/provider-usage.test.ts
@@ -227,6 +227,85 @@ describe("provider usage loading", () => {
    );
  });

+  it("prefers claude-cli token for Anthropic usage snapshots", async () => {
+    await withTempHome(
+      async () => {
+        const stateDir = process.env.CLAWDBOT_STATE_DIR;
+        if (!stateDir) throw new Error("Missing CLAWDBOT_STATE_DIR");
+        const agentDir = path.join(stateDir, "agents", "main", "agent");
+        fs.mkdirSync(agentDir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(
+          path.join(agentDir, "auth-profiles.json"),
+          `${JSON.stringify(
+            {
+              version: 1,
+              profiles: {
+                "anthropic:default": {
+                  type: "token",
+                  provider: "anthropic",
+                  token: "token-default",
+                  expires: Date.UTC(2100, 0, 1, 0, 0, 0),
+                },
+                "anthropic:claude-cli": {
+                  type: "token",
+                  provider: "anthropic",
+                  token: "token-cli",
+                  expires: Date.UTC(2100, 0, 1, 0, 0, 0),
+                },
+              },
+            },
+            null,
+            2,
+          )}\n`,
+          "utf8",
+        );
+
+        const makeResponse = (status: number, body: unknown): Response => {
+          const payload =
+            typeof body === "string" ? body : JSON.stringify(body);
+          const headers =
+            typeof body === "string"
+              ? undefined
+              : { "Content-Type": "application/json" };
+          return new Response(payload, { status, headers });
+        };
+
+        const mockFetch = vi.fn<
+          Parameters<typeof fetch>,
+          ReturnType<typeof fetch>
+        >(async (input, init) => {
+          const url =
+            typeof input === "string"
+              ? input
+              : input instanceof URL
+                ? input.toString()
+                : input.url;
+          if (url.includes("api.anthropic.com/api/oauth/usage")) {
+            const headers = (init?.headers ?? {}) as Record<string, string>;
+            expect(headers.Authorization).toBe("Bearer token-cli");
+            return makeResponse(200, {
+              five_hour: { utilization: 20, resets_at: "2026-01-07T01:00:00Z" },
+            });
+          }
+          return makeResponse(404, "not found");
+        });
+
+        const summary = await loadProviderUsageSummary({
+          now: Date.UTC(2026, 0, 7, 0, 0, 0),
+          providers: ["anthropic"],
+          agentDir,
+          fetch: mockFetch,
+        });
+
+        expect(summary.providers).toHaveLength(1);
+        expect(summary.providers[0]?.provider).toBe("anthropic");
+        expect(summary.providers[0]?.windows[0]?.label).toBe("5h");
+        expect(mockFetch).toHaveBeenCalled();
+      },
+      { prefix: "clawdbot-provider-usage-" },
+    );
+  });
+
  it("falls back to claude.ai web usage when OAuth scope is missing", async () => {
    const cookieSnapshot = process.env.CLAUDE_AI_SESSION_KEY;
    process.env.CLAUDE_AI_SESSION_KEY = "sk-ant-web-1";
--- a/src/infra/provider-usage.ts
+++ b/src/infra/provider-usage.ts
@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";

 import {
+  CLAUDE_CLI_PROFILE_ID,
  ensureAuthProfileStore,
  listProfilesForProvider,
  resolveApiKeyForProfile,
@@ -802,7 +803,16 @@ async function resolveOAuthToken(params: {
    provider: params.provider,
  });

-  for (const profileId of order) {
+  // Claude CLI creds are the only Anthropic tokens that reliably include the
+  // `user:profile` scope required for the OAuth usage endpoint.
+  const candidates =
+    params.provider === "anthropic" ? [CLAUDE_CLI_PROFILE_ID, ...order] : order;
+  const deduped: string[] = [];
+  for (const entry of candidates) {
+    if (!deduped.includes(entry)) deduped.push(entry);
+  }
+
+  for (const profileId of deduped) {
    const cred = store.profiles[profileId];
    if (!cred || (cred.type !== "oauth" && cred.type !== "token")) continue;
    try {