@vellumai/assistant 0.11.4 → 0.11.5-staging.2

package/src/acp/acp-claude-oauth.ts

@@ -17,16 +17,20 @@ import {
   getSecureKeyAsync,
   setSecureKeyAsync,
 } from "../security/secure-keys.js";
+import { getLogger } from "../util/logger.js";
 import {
   ACP_OAUTH_TOKEN_FIELD,
   ACP_SERVICE,
   classifyAnthropicToken,
 } from "./acp-credentials.js";
 import {
-  acpSpawnCanReadCredential,
-  grantAcpSpawnPolicy,
+  ACP_CLAUDE_OAUTH_USAGE_DESCRIPTION,
+  acpSpawnCredentialDenialReason,
+  repairAcpSpawnPolicy,
 } from "./prepare-agent-env.js";
 
+const log = getLogger("acp:claude-oauth");
+
 /**
  * Verified Claude Code public OAuth client. PKCE-only (no client secret);
  * the single `user:inference` scope is what the ACP adapter's
@@ -109,8 +113,9 @@ export function parseManualClaudeCode(input: string): {
 
 /**
  * Store a captured Claude OAuth token in the `acp/claude_oauth_token` vault
- * field and provision the `acp_spawn` read policy so the broker can inject it
- * at spawn time. Throws when the backing store rejects the write.
+ * field and provision the policy the broker applies at spawn time: grant the
+ * `acp_spawn` read and lift any domain restriction. Throws when the backing
+ * store rejects the write.
  */
 export async function storeAcpClaudeToken(token: string): Promise<void> {
   const stored = await setSecureKeyAsync(
@@ -120,13 +125,13 @@ export async function storeAcpClaudeToken(token: string): Promise<void> {
   if (!stored) {
     throw new Error("Failed to store Claude OAuth token in secure storage.");
   }
-  // Force-grant acp_spawn (union) rather than merely ensure it: an explicit
-  // Connect is a deliberate opt-in to ACP, so this repairs a credential whose
-  // explicit allowedTools omitted acp_spawn — otherwise the broker keeps denying
-  // the spawn read and the Connect card dead-loops on every auto-continue.
-  grantAcpSpawnPolicy(
+  // Repair rather than merely ensure the policy: an explicit Connect is a
+  // deliberate opt-in to ACP, so this widens a credential the broker would
+  // otherwise keep denying the spawn read on, which would dead-loop the Connect
+  // card on every auto-continue.
+  repairAcpSpawnPolicy(
     ACP_OAUTH_TOKEN_FIELD,
-    "Claude OAuth token for ACP agent authentication",
+    ACP_CLAUDE_OAUTH_USAGE_DESCRIPTION,
   );
 }
 
@@ -142,20 +147,32 @@ export async function storeAcpClaudeToken(token: string): Promise<void> {
  * spawn, so keeping Connect offered (rather than self-dismissing) lets the user
  * repair the bad entry by connecting a real OAuth token.
  *
- * Likewise, a token the `acp_spawn` policy can't read (an explicit
- * `allowedTools` that omits `acp_spawn`) is NOT connected: the vault holds a
- * value but the spawn's broker read is denied, so self-dismissing the card would
- * hide the only repair CTA while every spawn keeps failing. Keep the card up in
- * that denied-policy case too.
+ * Likewise, a token the spawn's broker read would be denied (an explicit
+ * `allowedTools` that omits `acp_spawn`, or a domain-restricted policy) is NOT
+ * connected: the vault holds a value but every spawn fails, so self-dismissing
+ * the card would hide the only repair CTA. That half of the answer is delegated
+ * to `acpSpawnCredentialDenialReason`, which evaluates the exact policy the
+ * spawn-time broker read applies, so "connected" means precisely "the spawn
+ * would get this token". The token-shape guard stays here instead: the broker
+ * knows nothing about Anthropic token formats.
  */
 export async function hasAcpClaudeToken(): Promise<boolean> {
   const token = await getSecureKeyAsync(
     credentialKey(ACP_SERVICE, ACP_OAUTH_TOKEN_FIELD),
   );
-  return (
-    token != null &&
-    token.length > 0 &&
-    classifyAnthropicToken(token) !== "api_key" &&
-    acpSpawnCanReadCredential(ACP_OAUTH_TOKEN_FIELD)
-  );
+  if (token == null || token.length === 0) {
+    return false;
+  }
+  if (classifyAnthropicToken(token) === "api_key") {
+    return false;
+  }
+  const denialReason = acpSpawnCredentialDenialReason(ACP_OAUTH_TOKEN_FIELD);
+  if (denialReason !== undefined) {
+    log.debug(
+      { field: ACP_OAUTH_TOKEN_FIELD, reason: denialReason },
+      "Connect Claude status: token present but spawn read would be denied",
+    );
+    return false;
+  }
+  return true;
 }

package/src/acp/prepare-agent-env.ts

@@ -25,9 +25,11 @@ import { basename } from "node:path";
 import { FailedDependencyError } from "../runtime/routes/errors.js";
 import { credentialBroker } from "../tools/credentials/broker.js";
 import {
+  type CredentialMetadata,
   getCredentialMetadata,
   upsertCredentialMetadata,
 } from "../tools/credentials/metadata-store.js";
+import { serverUseDenialReason } from "../tools/credentials/tool-policy.js";
 import { getLogger } from "../util/logger.js";
 import {
   ACP_OAUTH_TOKEN_FIELD,
@@ -40,91 +42,148 @@ const log = getLogger("acp:prepare-agent-env");
 
 const ACP_SPAWN_TOOL = "acp_spawn";
 
+/**
+ * `usageDescription` recorded on `acp/claude_oauth_token` when a record is
+ * created, shared by the spawn-time ensure and the Connect repair so the two
+ * paths can't describe the same credential differently.
+ */
+export const ACP_CLAUDE_OAUTH_USAGE_DESCRIPTION =
+  "Claude OAuth token for ACP agent authentication";
+
 /**
  * Stable, machine-readable marker carried on the `FailedDependencyError.details`
  * when a `claude-agent-acp` spawn is missing `CLAUDE_CODE_OAUTH_TOKEN`. Threaded
  * through the tool result / error payload as a structured field so clients can
  * offer the inline "Connect Claude Code" flow instead of re-parsing the human
  * message string. Kept in lockstep with the web literal in
- * `clients/web/src/domains/chat/transcript/acp-connect-affordance.tsx`.
+ * `clients/web/src/domains/chat/utils/acp-connect.ts`.
  */
 export const ACP_CLAUDE_OAUTH_MISSING_CODE = "acp_claude_oauth_missing";
 
 /**
- * Ensure an `acp/<field>` credential has metadata that allows the
- * `acp_spawn` tool to read it, but only for legacy/unmanaged cases:
+ * The metadata an `acp/<field>` credential has once the `acp_spawn` read policy
+ * is ensured, given what is stored now. This is the single definition of that
+ * decision: {@link ensureAcpCredentialPolicy} persists the result and
+ * {@link acpSpawnCredentialDenialReason} evaluates it without writing.
+ *
+ * The policy is only repaired for legacy/unmanaged cases:
+ *
+ * - No metadata at all: a record with `allowedTools: ["acp_spawn"]` and the
+ *   caller's `usageDescription`.
+ * - Metadata with an empty `allowedTools`: default provisioning path (user ran
+ *   `credentials set` without `--allowed-tools`), so `acp_spawn` is added.
+ * - Metadata with a non-empty `allowedTools`: explicit policy set by the
+ *   user/admin, returned as the very same object so callers can tell by
+ *   identity that there is nothing to persist. It stands even when `acp_spawn`
+ *   is absent; the broker denies the read and the caller decides whether that's
+ *   fatal.
  *
- * - No metadata at all: create with `allowedTools: ["acp_spawn"]`.
- * - Metadata exists with an empty `allowedTools`: default provisioning
- *   path (user ran `credentials set` without `--allowed-tools`), add it.
- * - Metadata exists with a non-empty `allowedTools`: explicit policy set
- *   by the user/admin. Respect it even if `acp_spawn` is absent; the
- *   broker will deny the read and the caller decides whether that's fatal.
+ * Everything else on an existing record, `allowedDomains` included, is
+ * preserved.
  */
-export function ensureAcpCredentialPolicy(
+function projectEnsuredAcpPolicy(
+  meta: CredentialMetadata | undefined,
   field: string,
-  usageDescription: string,
-): void {
-  const meta = getCredentialMetadata(ACP_SERVICE, field);
+  usageDescription?: string,
+): CredentialMetadata {
   if (!meta) {
-    upsertCredentialMetadata(ACP_SERVICE, field, {
+    return {
+      credentialId: "",
+      service: ACP_SERVICE,
+      field,
       allowedTools: [ACP_SPAWN_TOOL],
+      allowedDomains: [],
       usageDescription,
-    });
-    return;
+      createdAt: 0,
+      updatedAt: 0,
+    };
   }
-  const tools = meta.allowedTools ?? [];
-  if (tools.length === 0) {
-    upsertCredentialMetadata(ACP_SERVICE, field, {
-      allowedTools: [ACP_SPAWN_TOOL],
-    });
+  if ((meta.allowedTools ?? []).length === 0) {
+    return { ...meta, allowedTools: [ACP_SPAWN_TOOL] };
   }
+  return meta;
 }
 
 /**
- * Force-grant the `acp_spawn` read policy on `acp/<field>`, unioning it into any
- * existing `allowedTools`. Unlike {@link ensureAcpCredentialPolicy} (which
- * PRESERVES an explicit non-empty policy so a passive spawn can't silently widen
- * it), this is for the EXPLICIT Connect flow: a user connecting Claude is a
- * deliberate opt-in to `acp_spawn`, so granting it makes the CTA actually repair
- * a policy-denied credential instead of dead-looping the missing-token card.
+ * Bring the stored metadata for `acp/<field>` up to the policy
+ * {@link projectEnsuredAcpPolicy} describes, writing only the fields that
+ * projection decides and only when it differs from what is stored.
  */
-export function grantAcpSpawnPolicy(
+export function ensureAcpCredentialPolicy(
   field: string,
   usageDescription: string,
 ): void {
   const meta = getCredentialMetadata(ACP_SERVICE, field);
-  if (!meta) {
-    upsertCredentialMetadata(ACP_SERVICE, field, {
-      allowedTools: [ACP_SPAWN_TOOL],
-      usageDescription,
-    });
+  const ensured = projectEnsuredAcpPolicy(meta, field, usageDescription);
+  if (ensured === meta) {
     return;
   }
-  const tools = meta.allowedTools ?? [];
-  if (!tools.includes(ACP_SPAWN_TOOL)) {
-    upsertCredentialMetadata(ACP_SERVICE, field, {
-      allowedTools: [...tools, ACP_SPAWN_TOOL],
-    });
-  }
+  upsertCredentialMetadata(ACP_SERVICE, field, {
+    allowedTools: ensured.allowedTools,
+    usageDescription: ensured.usageDescription,
+  });
 }
 
 /**
- * Whether the `acp_spawn` broker read for `acp/<field>` would actually be
- * permitted, mirroring {@link ensureAcpCredentialPolicy}'s grant rules: a
- * missing or empty `allowedTools` is auto-granted `acp_spawn` at spawn time, so
- * it can read; a non-empty explicit policy is respected as-is, so it can read
- * only when it lists `acp_spawn`. Lets a connected-status check avoid reporting
- * "connected" for a token the spawn is policy-denied from reading (which would
- * otherwise hide the repair CTA and trap the user in a missing-token loop).
+ * Make `acp/<field>` readable by the spawn: union `acp_spawn` into any existing
+ * `allowedTools` and drop any domain restriction, in ONE write and only when the
+ * stored record fails either half. This is the whole repair the Connect flow
+ * performs, so a new dimension of {@link serverUseDenialReason} is repaired in
+ * exactly one place.
+ *
+ * Unlike {@link ensureAcpCredentialPolicy} (which PRESERVES an explicit non-empty
+ * policy so a passive spawn can't silently widen it), this is for the EXPLICIT
+ * Connect flow: a user connecting Claude is a deliberate opt-in to `acp_spawn`,
+ * so granting it makes the CTA actually repair a policy-denied credential instead
+ * of dead-looping the missing-token card. Domains are cleared under the same
+ * opt-in: this field is OAuth-only and server-use-only, and the broker refuses a
+ * domain-restricted credential server-side, so a lingering restriction would keep
+ * every spawn failing even after a successful connect.
  */
-export function acpSpawnCanReadCredential(field: string): boolean {
+export function repairAcpSpawnPolicy(
+  field: string,
+  usageDescription: string,
+): void {
   const meta = getCredentialMetadata(ACP_SERVICE, field);
-  if (!meta) {
-    return true;
+  const tools = meta?.allowedTools ?? [];
+  const spawnAllowed = tools.includes(ACP_SPAWN_TOOL);
+  const domainUnrestricted = (meta?.allowedDomains ?? []).length === 0;
+  if (meta && spawnAllowed && domainUnrestricted) {
+    return;
   }
-  const tools = meta.allowedTools ?? [];
-  return tools.length === 0 || tools.includes(ACP_SPAWN_TOOL);
+  upsertCredentialMetadata(ACP_SERVICE, field, {
+    allowedTools: spawnAllowed ? tools : [...tools, ACP_SPAWN_TOOL],
+    allowedDomains: [],
+    // Only a fresh record takes the description; an existing one keeps its own.
+    ...(meta ? {} : { usageDescription }),
+  });
+}
+
+/**
+ * Why the `acp_spawn` broker read for `acp/<field>` would be denied, or
+ * `undefined` when it would be permitted. Lets a connected-status check avoid
+ * reporting "connected" for a token the spawn is policy-denied from reading
+ * (which would otherwise hide the repair CTA and trap the user in a
+ * missing-token loop).
+ *
+ * The verdict comes from `serverUseDenialReason`, the single policy source the
+ * broker itself consults, so the status check and the spawn read can never
+ * disagree. The stored metadata is first run through
+ * {@link projectEnsuredAcpPolicy}, the same repair the spawn persists, computed
+ * in memory and never written: this runs on a side-effect-free GET route, so it
+ * has to predict what the spawn's ensure-then-read sequence would do rather
+ * than perform it.
+ */
+export function acpSpawnCredentialDenialReason(
+  field: string,
+): string | undefined {
+  const meta = getCredentialMetadata(ACP_SERVICE, field);
+  return serverUseDenialReason(
+    projectEnsuredAcpPolicy(meta, field),
+    ACP_SPAWN_TOOL,
+    ACP_SERVICE,
+    field,
+  );
 }
 
 /**
@@ -243,25 +302,57 @@ export async function prepareAgentEnv(
     };
 
     dropApiKeyOauthToken();
+    let missReason: string | undefined;
     if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
-      await injectCredential(
+      missReason = await injectCredential(
         env,
         ACP_OAUTH_TOKEN_FIELD,
         "CLAUDE_CODE_OAUTH_TOKEN",
-        "Claude OAuth token for ACP agent authentication",
+        ACP_CLAUDE_OAUTH_USAGE_DESCRIPTION,
       );
     }
+    // Any api-key-shaped value still standing here came from the vault read:
+    // the config override was already dropped above, and the read only runs
+    // when the override left the var unset.
+    const storedValueIsApiKeyShaped =
+      env.CLAUDE_CODE_OAUTH_TOKEN !== undefined &&
+      classifyAnthropicToken(env.CLAUDE_CODE_OAUTH_TOKEN) === "api_key";
     dropApiKeyOauthToken();
     if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
+      // The operator's record of WHY the spawn has no token. `missReason` is
+      // the broker's own reason string and the rest are policy verdicts, so no
+      // field can carry the credential value.
+      const policyDenialReason = acpSpawnCredentialDenialReason(
+        ACP_OAUTH_TOKEN_FIELD,
+      );
+      log.warn(
+        {
+          field: ACP_OAUTH_TOKEN_FIELD,
+          missReason,
+          policyBlocked: policyDenialReason !== undefined,
+          apiKeyShaped: storedValueIsApiKeyShaped,
+        },
+        "Claude OAuth token not injected for acp_spawn",
+      );
       // Carry the stable marker as structured `details` so the client renders
       // the inline "Connect Claude Code" card. The message itself is the tool
       // result the model reads at the failure moment, so it directs the model
       // AT that card and away from CLI/token-paste workarounds — otherwise the
       // model relays a `claude setup-token` / paste-a-token flow that the card
       // exists to replace. The CLI command stays only as a headless fallback.
+      // A policy-blocked read is a different repair story from an absent value,
+      // so the opening states which one happened. The guidance after it is
+      // shared: the Connect card fixes both.
+      const opening = policyDenialReason
+        ? "claude-agent-acp cannot read the Claude OAuth token: the credential " +
+          "policy on acp/claude_oauth_token blocks the acp_spawn read, so " +
+          "CLAUDE_CODE_OAUTH_TOKEN is not set for the spawn. Clicking Connect " +
+          "signs in again and repairs that policy. "
+        : "claude-agent-acp needs a Claude OAuth token (CLAUDE_CODE_OAUTH_TOKEN), " +
+          "which is not set. ";
       throw new FailedDependencyError(
-        "claude-agent-acp needs a Claude OAuth token (CLAUDE_CODE_OAUTH_TOKEN), " +
-          'which is not set. The app shows the user an inline "Connect Claude ' +
+        opening +
+          'The app shows the user an inline "Connect Claude ' +
           'Code" card. Reply with ONE short sentence: ask them to click Connect ' +
           "in that card to sign in, and tell them you'll continue automatically " +
           "once they're connected. Do NOT say where the card is — never say " +

package/src/agent/loop-tool-dedup.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Verifies the agent loop coalesces `tool_use` blocks by call id before it
+ * dispatches them: a provider that emits the same call twice under one id gets
+ * one execution, one `tool_use` block in history, and one correlated
+ * `tool_result`. Distinct ids for the same tool name still run independently.
+ * Drives the REAL loop, mocking only the provider boundary.
+ */
+import { describe, expect, test } from "bun:test";
+
+import { createMockProvider } from "../__tests__/helpers/mock-provider.js";
+import type { ContentBlock, ProviderResponse } from "../providers/types.js";
+import { AgentLoop } from "./loop.js";
+
+const endTurn = (text: string): ProviderResponse => ({
+  content: [{ type: "text", text }],
+  model: "mock-model",
+  usage: { inputTokens: 1, outputTokens: 1 },
+  stopReason: "end_turn",
+});
+
+const toolUseTurn = (
+  blocks: Array<{ id: string; name: string }>,
+): ProviderResponse => ({
+  content: [
+    { type: "text", text: "working" },
+    ...blocks.map((b) => ({
+      type: "tool_use" as const,
+      id: b.id,
+      name: b.name,
+      input: {},
+    })),
+  ],
+  model: "mock-model",
+  usage: { inputTokens: 1, outputTokens: 1 },
+  stopReason: "tool_use",
+});
+
+function blocksOfType<T extends ContentBlock["type"]>(
+  history: Array<{ content: ContentBlock[] }>,
+  type: T,
+): Array<Extract<ContentBlock, { type: T }>> {
+  return history
+    .flatMap((m) => m.content)
+    .filter((b): b is Extract<ContentBlock, { type: T }> => b.type === type);
+}
+
+function buildLoop(
+  provider: ReturnType<typeof createMockProvider>["provider"],
+  conversationId: string,
+  executed: string[],
+) {
+  return new AgentLoop({
+    provider,
+    systemPrompt: "sys",
+    conversationId,
+    tools: [
+      { name: "read_file", description: "", input_schema: { type: "object" } },
+    ],
+    toolExecutor: async (name) => {
+      executed.push(name);
+      return { content: `ran ${name}`, isError: false };
+    },
+  });
+}
+
+const baseRun = {
+  requestId: "req-dedup",
+  onEvent: () => {},
+  callSite: "mainAgent" as const,
+  trust: { sourceChannel: "vellum" as const, trustClass: "unknown" as const },
+  messages: [
+    { role: "user" as const, content: [{ type: "text" as const, text: "go" }] },
+  ],
+};
+
+describe("AgentLoop: duplicate tool_use ids", () => {
+  /** A call the provider emits twice under one id runs a single time. */
+  test("executes a call id once when the provider emits it twice", async () => {
+    // GIVEN a provider turn carrying the same tool_use id twice
+    const { provider } = createMockProvider([
+      toolUseTurn([
+        { id: "call-dup", name: "read_file" },
+        { id: "call-dup", name: "read_file" },
+      ]),
+      endTurn("done"),
+    ]);
+
+    // WHEN the loop runs the turn
+    const executed: string[] = [];
+    const toolUseEventIds: string[] = [];
+    const { history } = await buildLoop(provider, "dedup-1", executed).run({
+      ...baseRun,
+      onEvent: (event) => {
+        if (event.type === "tool_use") {
+          toolUseEventIds.push(event.id);
+        }
+      },
+    });
+
+    // THEN the tool runs once and the client sees one tool_use
+    expect(executed).toEqual(["read_file"]);
+    expect(toolUseEventIds).toEqual(["call-dup"]);
+
+    // AND history stays well-formed: providers require one tool_result per
+    // tool_use id, so the coalesced copy must not survive into history.
+    const toolUses = blocksOfType(history, "tool_use");
+    expect(toolUses.map((b) => b.id)).toEqual(["call-dup"]);
+    const results = blocksOfType(history, "tool_result");
+    expect(results.map((b) => b.tool_use_id)).toEqual(["call-dup"]);
+    expect(results[0]!.content).toBe("ran read_file");
+    expect(results[0]!.is_error).toBe(false);
+  });
+
+  /** Two independent calls of one tool are not collapsed by name. */
+  test("runs repeat calls of one tool when their ids differ", async () => {
+    // GIVEN a provider turn calling one tool twice under distinct ids
+    const { provider } = createMockProvider([
+      toolUseTurn([
+        { id: "call-a", name: "read_file" },
+        { id: "call-b", name: "read_file" },
+      ]),
+      endTurn("done"),
+    ]);
+
+    // WHEN the loop runs the turn
+    const executed: string[] = [];
+    const { history } = await buildLoop(provider, "dedup-2", executed).run(
+      baseRun,
+    );
+
+    // THEN both calls execute and each gets its own result
+    expect(executed).toEqual(["read_file", "read_file"]);
+    expect(
+      blocksOfType(history, "tool_result").map((b) => b.tool_use_id),
+    ).toEqual(["call-a", "call-b"]);
+  });
+
+  /** An id-less call still executes, under a generated id. */
+  test("assigns a call id when the provider emits a tool_use without one", async () => {
+    // GIVEN a provider turn whose tool_use block carries no id
+    const { provider } = createMockProvider([
+      toolUseTurn([{ id: "", name: "read_file" }]),
+      endTurn("done"),
+    ]);
+
+    // WHEN the loop runs the turn
+    const executed: string[] = [];
+    const { history } = await buildLoop(provider, "dedup-3", executed).run(
+      baseRun,
+    );
+
+    // THEN the call executes under a generated id its result correlates to
+    expect(executed).toEqual(["read_file"]);
+    const toolUses = blocksOfType(history, "tool_use");
+    expect(toolUses).toHaveLength(1);
+    expect(toolUses[0]!.id.length).toBeGreaterThan(0);
+    expect(
+      blocksOfType(history, "tool_result").map((b) => b.tool_use_id),
+    ).toEqual([toolUses[0]!.id]);
+  });
+});

package/src/agent/loop.ts

@@ -31,6 +31,7 @@ import { defaultCompact } from "../plugins/defaults/compaction/compact.js";
 import type { ContextWindowResult } from "../plugins/defaults/compaction/window-manager.js";
 import { runHook } from "../plugins/pipeline.js";
 import type { CompactionCircuitEvent } from "../plugins/types.js";
+import { hasVisibleText } from "../providers/content-blocks.js";
 import { isMaxTokensStopReason } from "../providers/stop-reasons.js";
 import { normalizeThinkingConfigForWire } from "../providers/thinking-config.js";
 import type {
@@ -528,13 +529,6 @@ function assistantTextOf(content: ReadonlyArray<ContentBlock>): string {
   return text;
 }
 
-/** Whether `content` carries at least one non-empty `text` block. */
-function hasVisibleText(content: ReadonlyArray<ContentBlock>): boolean {
-  return content.some(
-    (block) => block.type === "text" && block.text.trim().length > 0,
-  );
-}
-
 type AgentLoopContextWindowResolver = () => {
   maxInputTokens: number;
   overflowRecovery: { enabled: boolean; safetyMarginRatio: number };
@@ -704,10 +698,56 @@ export type LoopToolExecutor = (
   errorCode?: string;
 }>;
 
+type ToolUseBlock = Extract<ContentBlock, { type: "tool_use" }>;
+
+interface NormalizedToolUse {
+  /** Assistant content with at most one `tool_use` block per call id. */
+  content: ContentBlock[];
+  /** The `tool_use` blocks in `content`, in order. */
+  toolUseBlocks: ToolUseBlock[];
+  /** Coalesced copies: a call id and name for each block dropped. */
+  duplicates: Array<{ id: string; name: string }>;
+}
+
+/**
+ * Resolves an assistant reply's `tool_use` blocks into an executable set keyed
+ * by call id: a block with no id gets one, and a repeat of an id already in the
+ * reply is dropped so the call runs once and its single `tool_result` correlates
+ * unambiguously. Providers occasionally emit the same call twice under one id,
+ * and both Anthropic and OpenAI require one `tool_result` per `tool_use` id, so
+ * the duplicate has no well-formed representation downstream.
+ */
+function normalizeToolUseBlocks(
+  content: ReadonlyArray<ContentBlock>,
+): NormalizedToolUse {
+  const nextContent: ContentBlock[] = [];
+  const toolUseBlocks: ToolUseBlock[] = [];
+  const duplicates: Array<{ id: string; name: string }> = [];
+  const seenIds = new Set<string>();
+
+  for (const block of content) {
+    if (block.type !== "tool_use") {
+      nextContent.push(block);
+      continue;
+    }
+    if (seenIds.has(block.id)) {
+      duplicates.push({ id: block.id, name: block.name });
+      continue;
+    }
+    const normalized: ToolUseBlock =
+      block.id.length === 0 ? { ...block, id: crypto.randomUUID() } : block;
+    seenIds.add(normalized.id);
+    nextContent.push(normalized);
+    toolUseBlocks.push(normalized);
+  }
+
+  return { content: nextContent, toolUseBlocks, duplicates };
+}
+
 /**
  * The benign result returned for a sibling tool call that was deferred because
  * an exclusive tool ran in the same turn. Phrased so the model treats it as a
- * "not run yet" signal — read the exclusive tool's output, then re-issue this
+ * "not run yet" signal: read the exclusive tool's output, then re-issue this
  * call if it is still the right next step.
  */
 function deferredForExclusiveMessage(exclusiveToolName: string): string {
@@ -1176,7 +1216,7 @@ export class AgentLoop {
         "Agent loop iteration start",
       );
 
-      let toolUseBlocks: Extract<ContentBlock, { type: "tool_use" }>[] = [];
+      let toolUseBlocks: ToolUseBlock[] = [];
       // The provider rejection thrown by this iteration's call, if any. Set in
       // the inner provider catch and read by the outer catch to confine
       // error-stop recovery to genuine provider rejections — a throw from
@@ -1864,8 +1904,7 @@ export class AgentLoop {
         // the `post-model-call` hook below, which may add or drop tool calls;
         // this raw set drives only the completion log and the max-tokens branch.
         const modelToolUseBlocks = response.content.filter(
-          (block): block is Extract<ContentBlock, { type: "tool_use" }> =>
-            block.type === "tool_use",
+          (block): block is ToolUseBlock => block.type === "tool_use",
         );
 
         rlog.info(
@@ -1979,19 +2018,26 @@ export class AgentLoop {
         // if the model had called it (the supported way for a plugin to surface
         // a card or take a follow-up action), or drop one the model emitted, so
         // the loop runs whatever the assistant message ends up carrying.
-        // Normalize ids so the executor and tool_result correlation stay 1:1 —
-        // a hook-added block may carry an empty or duplicate id.
-        toolUseBlocks = assistantMessage.content.filter(
-          (block): block is Extract<ContentBlock, { type: "tool_use" }> =>
-            block.type === "tool_use",
+        // Normalizing ids keeps executor dispatch and tool_result correlation
+        // 1:1 for the rest of the turn.
+        const normalizedToolUse = normalizeToolUseBlocks(
+          assistantMessage.content,
         );
-        const seenToolUseIds = new Set<string>();
-        for (const block of toolUseBlocks) {
-          if (block.id.length === 0 || seenToolUseIds.has(block.id)) {
-            block.id = crypto.randomUUID();
-          }
-          seenToolUseIds.add(block.id);
+        for (const duplicate of normalizedToolUse.duplicates) {
+          rlog.warn(
+            {
+              turn: toolUseTurns,
+              duplicateId: duplicate.id,
+              duplicateName: duplicate.name,
+            },
+            "Duplicate tool_use id in the assistant reply, coalescing into a single call",
+          );
         }
+        assistantMessage = {
+          ...assistantMessage,
+          content: normalizedToolUse.content,
+        };
+        toolUseBlocks = normalizedToolUse.toolUseBlocks;
 
         // At the no-tool stop boundary the retry decision is actionable: a
         // recovery hook may repair history and ask to re-query (a tool-bearing