@vellumai/assistant 0.8.7 → 0.8.8

package/src/plugins/defaults/memory-retrieval/hooks/post-compact.ts

@@ -0,0 +1,91 @@
+/**
+ * Default `memoryRetrieval` post-compaction hook.
+ *
+ * After the agent loop compacts a conversation mid-turn it must re-apply the
+ * runtime injections compaction stripped — the NOW.md scratchpad, PKB context,
+ * memory-v2 static block, workspace top-level context, and Slack chronological
+ * snapshot — onto the compacted history before the turn continues. This hook
+ * is the memory system's home for that transform: it receives the message
+ * history plus the resolved runtime-injection options and returns the edited
+ * history (and the blocks it captured), with no dependency on the agent loop's
+ * closure state.
+ *
+ * It re-applies the runtime injections via {@link applyRuntimeInjections},
+ * re-tracks the memory graph's cached nodes against the re-injected history,
+ * and converts now-historical `web_search_tool_result` blocks to text so their
+ * expired `encrypted_content` tokens are not replayed. The remaining
+ * orchestrator-side step (the post-injection bookkeeping the loop records) is
+ * expected to migrate here as the hook subsumes the loop's re-injection
+ * ceremony.
+ *
+ * The memory graph handle is sourced internally from the plugin's own
+ * conversation-keyed registry ({@link getLiveGraphMemory}) rather than being
+ * threaded in by the loop — it is memory-retrieval-specific state, not
+ * something the generic loop or the shared {@link TurnContext} should carry.
+ */
+
+import {
+  applyRuntimeInjections,
+  type RuntimeInjectionOptions,
+  type RuntimeInjectionResult,
+} from "../../../../daemon/conversation-runtime-assembly.js";
+import { stripHistoricalWebSearchResults } from "../../../../daemon/web-search-history.js";
+import { getLiveGraphMemory } from "../../../../memory/graph/conversation-graph-memory.js";
+import type { PluginLogger } from "../../../../plugin-api/types.js";
+import type { Message } from "../../../../providers/types.js";
+import type { TurnContext } from "../../../types.js";
+
+/**
+ * The slice of the hook's context the agent loop supplies from its own working
+ * state. Re-injection inputs migrate loop-ward by growing this type; the loop
+ * hands the hook an object of this shape via
+ * {@link MidLoopCompaction.postCompactionHook}.
+ */
+export interface PostCompactionHookInput {
+  /** Compacted message history to re-inject onto. */
+  history: Message[];
+  /** Per-turn conversation context forwarded to the injector chain. */
+  turnContext?: TurnContext;
+}
+
+/**
+ * Everything the hook needs in a single context: the loop-supplied
+ * {@link PostCompactionHookInput}, the resolved {@link RuntimeInjectionOptions}
+ * (spread top-level so each field stays individually addressable), and the
+ * conversation-scoped state the options bag cannot carry (actor trust and a
+ * turn-scoped logger). The memory graph handle is not part of this context —
+ * the hook sources it internally via {@link getLiveGraphMemory}.
+ */
+export interface PostCompactContext
+  extends RuntimeInjectionOptions, PostCompactionHookInput {
+  /** True when the actor for this turn is trusted (guardian-class). */
+  isTrustedActor: boolean;
+  /** Turn-scoped logger for diagnostics emitted while re-injecting. */
+  logger: PluginLogger;
+}
+
+export default async function postCompactReinject(
+  ctx: PostCompactContext,
+): Promise<RuntimeInjectionResult> {
+  const { history, isTrustedActor, logger, ...options } = ctx;
+  const result = await applyRuntimeInjections(history, options);
+  // Re-track the nodes the memory graph last injected so they survive against
+  // the re-injected history. Untrusted actors and minimal-mode turns never
+  // received a memory-graph injection, so there is nothing to re-track. The
+  // live graph handle is looked up from the plugin's own registry by the
+  // turn's conversation id — the same instance the turn's retrieval mutated,
+  // so re-tracking sees the real cached-node state.
+  if (isTrustedActor && options.mode !== "minimal") {
+    getLiveGraphMemory(
+      options.turnContext?.conversationId,
+    )?.retrackCachedNodes();
+  }
+  const strip = stripHistoricalWebSearchResults(result.messages);
+  if (strip.stats.blocksStripped > 0) {
+    logger.info(
+      { phase: "mid-loop-compact", ...strip.stats },
+      "Converted historical web_search_tool_result blocks to text summaries",
+    );
+  }
+  return { ...result, messages: strip.messages };
+}

package/src/plugins/defaults/memory-retrieval/hooks/user-prompt-submit-temp.ts

@@ -0,0 +1,216 @@
+/**
+ * Default `user-prompt-submit-temp` hook: runs the memory-graph retrieval the
+ * agent loop needs before building a turn's runtime-injection block.
+ *
+ * **Memory graph** via {@link ConversationGraphMemory.prepareMemory} —
+ * dispatches to context-load or per-turn retrieval depending on initialization
+ * state; gated on the actor being trusted (guardian).
+ *
+ * The hook also owns the retrieval's side effects — persisting the injected
+ * block onto the user message's metadata, writing the recall log, and emitting
+ * the `memory_recalled` event — so the loop only consumes the turn-scoped
+ * `latestMessages` written back onto the context. The PKB query-vector pair is
+ * recorded on the conversation's graph handle for the PKB-reminder injector to
+ * read back. PKB context and NOW.md are sourced directly by their injectors
+ * (gated on block presence), not produced here.
+ *
+ * This fires at the early "prompt submitted, before context assembly" moment,
+ * distinct from the canonical late `user-prompt-submit` hook (history repair,
+ * title): memory's outputs feed the injection and overflow-reduction transforms
+ * that run between the two moments. The `-temp` suffix marks this as a
+ * transitional staging point that folds into `user-prompt-submit` once
+ * compaction is cleared from the gap between the two call sites.
+ */
+
+import type { PluginHookFn } from "@vellumai/plugin-api";
+import type { Logger } from "pino";
+
+import type { AssistantConfig } from "../../../../config/schema.js";
+import type { ServerMessage } from "../../../../daemon/message-protocol.js";
+import type { MemoryRecalled } from "../../../../daemon/message-types/memory.js";
+import { updateMessageMetadata } from "../../../../memory/conversation-crud.js";
+import type { ConversationGraphMemory } from "../../../../memory/graph/conversation-graph-memory.js";
+import { recordMemoryRecallLog } from "../../../../memory/memory-recall-log-store.js";
+import type { Message } from "../../../../providers/types.js";
+import type { GraphMemoryResult } from "../../../types.js";
+
+/**
+ * Context threaded through the `user-prompt-submit-temp` hook. The readonly
+ * fields carry the conversation-scoped state the retriever needs (graph
+ * handle, event sink, abort signal); the output fields are populated by the
+ * hook and read back by the agent loop. `latestMessages` straddles both: the
+ * loop seeds it with the pre-injection array and the hook overwrites it with
+ * the injected result.
+ */
+export interface MemoryRetrievalHookContext {
+  /** Per-conversation memory graph handle. */
+  readonly graphMemory: ConversationGraphMemory;
+  /** Assistant config snapshot. */
+  readonly config: AssistantConfig;
+  /** Event sink used by the graph retriever and `memory_recalled` emission. */
+  readonly onEvent: (msg: ServerMessage) => void;
+  /** True when the actor for this turn is trusted (guardian-class). */
+  readonly isTrustedActor: boolean;
+  /** Conversation the turn belongs to — keys the recall-log row. */
+  readonly conversationId: string;
+  /** User message the injected memory block is persisted onto. */
+  readonly userMessageId: string;
+  /** Turn-scoped logger for non-fatal persistence warnings. */
+  readonly logger: Logger;
+  /**
+   * Per-turn abort signal forwarded to `prepareMemory`. An external cancel
+   * aborts the underlying retrieval instead of letting it run to completion.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Working message list for the turn. Seeded by the loop with the
+   * pre-injection messages and consumed as the retrieval input; the hook
+   * overwrites it with the memory-graph block injected, or leaves it
+   * unchanged when no graph retrieval ran (untrusted actor, or a no-op
+   * retrieval). Read back by the loop.
+   */
+  latestMessages: Message[];
+}
+
+/**
+ * Persist and broadcast the retrieval's side effects: the injected block on
+ * the user message's metadata (so it survives reloads), a recall-log row, and
+ * the `memory_recalled` debug event. All three are best-effort — a failure to
+ * persist must not abort the turn.
+ */
+function recordRecallSideEffects(
+  graphResult: GraphMemoryResult,
+  ctx: MemoryRetrievalHookContext,
+): void {
+  // Persist the injected block text in message metadata so it survives
+  // conversation reloads (eviction, restart, fork). loadFromDb re-injects
+  // from metadata.
+  if (graphResult.injectedBlockText) {
+    try {
+      updateMessageMetadata(ctx.userMessageId, {
+        memoryInjectedBlock: graphResult.injectedBlockText,
+      });
+    } catch (err) {
+      ctx.logger.warn(
+        { err },
+        "Failed to persist memory injection to metadata (non-fatal)",
+      );
+    }
+  }
+
+  const m = graphResult.metrics;
+
+  try {
+    recordMemoryRecallLog({
+      conversationId: ctx.conversationId,
+      enabled: true,
+      degraded: false,
+      provider: m?.embeddingProvider ?? undefined,
+      model: m?.embeddingModel ?? undefined,
+      semanticHits: m?.semanticHits ?? 0,
+      mergedCount: m?.mergedCount ?? 0,
+      selectedCount: m?.selectedCount ?? 0,
+      tier1Count: m?.tier1Count ?? 0,
+      tier2Count: m?.tier2Count ?? 0,
+      hybridSearchLatencyMs: m?.hybridSearchLatencyMs ?? 0,
+      sparseVectorUsed: m?.sparseVectorUsed ?? false,
+      injectedTokens: graphResult.injectedTokens,
+      latencyMs: graphResult.latencyMs,
+      topCandidatesJson: (m?.topCandidates ?? []).map((c) => ({
+        key: c.nodeId,
+        type: c.type,
+        kind: "graph",
+        finalScore: c.score,
+        semantic: c.semanticSimilarity,
+        recency: c.recencyBoost,
+      })),
+      injectedText: graphResult.injectedBlockText ?? undefined,
+      reason: `graph:${graphResult.mode}`,
+      queryContext: m?.queryContext ?? undefined,
+    });
+  } catch (err) {
+    ctx.logger.warn({ err }, "Failed to persist memory recall log (non-fatal)");
+  }
+
+  if (m) {
+    const memoryRecalledEvent: MemoryRecalled = {
+      type: "memory_recalled",
+      provider: m.embeddingProvider ?? "unknown",
+      model: m.embeddingModel ?? "unknown",
+      semanticHits: m.semanticHits,
+      mergedCount: m.mergedCount,
+      selectedCount: m.selectedCount,
+      tier1Count: m.tier1Count,
+      tier2Count: m.tier2Count,
+      hybridSearchLatencyMs: m.hybridSearchLatencyMs,
+      sparseVectorUsed: m.sparseVectorUsed,
+      injectedTokens: graphResult.injectedTokens,
+      latencyMs: graphResult.latencyMs,
+      topCandidates: m.topCandidates.map((c) => ({
+        key: c.nodeId,
+        type: c.type,
+        kind: "graph",
+        finalScore: c.score,
+        semantic: c.semanticSimilarity,
+        recency: c.recencyBoost,
+      })),
+    };
+    ctx.onEvent(memoryRecalledEvent);
+  }
+}
+
+/**
+ * Run the default retrieval, writing `latestMessages` back onto the context and
+ * recording the PKB query-vector pair on the graph handle. Skips the
+ * memory-graph call entirely (leaving `latestMessages` as the seeded input
+ * messages and no query pair recorded) when the actor is not trusted.
+ *
+ * Memory retrieval blocks the turn — there is no soft timeout here. Memory is
+ * critical context, and silently dropping it produces a worse outcome than a
+ * slower turn. Cancellation still works via `ctx.signal`, which is threaded
+ * into `prepareMemory`.
+ */
+const userPromptSubmitMemoryRetrieval: PluginHookFn<
+  MemoryRetrievalHookContext
+> = async (ctx) => {
+  if (!ctx.isTrustedActor) {
+    // Untrusted actors skip memory-graph retrieval entirely.
+    return;
+  }
+
+  const graphResult = await ctx.graphMemory.prepareMemory(
+    ctx.latestMessages,
+    ctx.config,
+    ctx.signal,
+    ctx.onEvent,
+  );
+
+  recordRecallSideEffects(graphResult, ctx);
+
+  ctx.latestMessages = graphResult.runMessages;
+  // Select dense+sparse as a matched pair so RRF fusion combines two signals
+  // aligned to the same query text:
+  //   1. Context-load with a user query: user-query dense + user-query sparse
+  //      — the cleanest pairing.
+  //   2. Otherwise (context-load without a user query, or per-turn): whatever
+  //      `queryVector` / `sparseVector` the retriever produced, which are
+  //      themselves co-aligned (both summary-derived in context-load, both
+  //      user-last-message-derived in per-turn).
+  // Never pair a user-query dense with a summary-aligned sparse.
+  // The PKB-reminder injector reads this pair back off the same graph handle
+  // (looked up by conversation id) rather than receiving it threaded through
+  // the agent loop.
+  if (graphResult.userQueryVector) {
+    ctx.graphMemory.recordPkbQueryVectors(
+      graphResult.userQueryVector,
+      graphResult.userQuerySparseVector,
+    );
+  } else {
+    ctx.graphMemory.recordPkbQueryVectors(
+      graphResult.queryVector,
+      graphResult.sparseVector,
+    );
+  }
+};
+
+export default userPromptSubmitMemoryRetrieval;

package/src/plugins/defaults/memory-retrieval/injector-chain.ts

@@ -0,0 +1,35 @@
+/**
+ * The assembled runtime injector chain.
+ *
+ * Injection is not a plugin contribution: the first-party injectors are
+ * imported directly and sorted once, by ascending `order`, into the single
+ * sequence `applyRuntimeInjections` walks each turn. This co-locates the
+ * chain with the memory-retrieval domain it serves, rather than aggregating
+ * injectors out of the plugin registry.
+ *
+ * The chain combines the default injectors ({@link defaultInjectors}) with the
+ * memory-v3 injector ({@link memoryV3Injector}). The sort mirrors the previous
+ * registry aggregation (`Array.prototype.sort` is stable, so injectors sharing
+ * an `order` keep their listed order), so the produced sequence — and therefore
+ * the injected content — is identical.
+ *
+ * The chain is assembled lazily on first access and memoized, so the sort runs
+ * once per process rather than per turn and module evaluation stays free of any
+ * ordering assumptions about when `defaultInjectors` finishes initializing.
+ */
+
+import { memoryV3Injector } from "../../../memory/v3/shadow-plugin.js";
+import type { Injector } from "../../types.js";
+import { defaultInjectors } from "../injectors/register.js";
+
+let cachedChain: Injector[] | null = null;
+
+/** The order-sorted runtime injector chain, assembled once and memoized. */
+export function getInjectorChain(): Injector[] {
+  if (cachedChain === null) {
+    cachedChain = [...defaultInjectors, memoryV3Injector].sort(
+      (a, b) => a.order - b.order,
+    );
+  }
+  return cachedChain;
+}

package/src/plugins/defaults/title-generate/hooks/stop.ts

@@ -0,0 +1,75 @@
+/**
+ * Default `stop` hook: triggers the second-pass conversation-title
+ * regeneration once a conversation has accumulated enough context.
+ *
+ * The first title is generated from the opening prompt alone (see
+ * `./user-prompt-submit.ts`). After a few exchanges the conversation's real
+ * topic is usually clearer, so a single second pass re-titles using the most
+ * recent messages. This hook is the trigger — it fires the regeneration when
+ * the conversation reaches its third user turn — and delegates the title
+ * itself to the service (`memory/conversation-title-service.ts`), which
+ * re-checks that the title is still auto-generated, resolves the title
+ * provider, persists, and broadcasts the `conversation_title_updated` /
+ * `sync_changed` events.
+ *
+ * Turn count is read from history rather than an external counter: the number
+ * of genuine user prompts — user-role messages that aren't purely tool results
+ * — is the conversation's turn number. Deriving it from history keeps the hook
+ * stateless and means a mid-run array rewrite (compaction) can't invalidate it.
+ */
+
+import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+
+import { getConfig } from "../../../../config/loader.js";
+import { queueRegenerateConversationTitle } from "../../../../memory/conversation-title-service.js";
+import type { Message } from "../../../../providers/types.js";
+
+/**
+ * User turn at which the second title pass fires. Matches the
+ * `conversations.skipAutoRetitling` opt-out, documented as skipping the
+ * regeneration "that fires after the third user turn".
+ */
+const SECOND_PASS_USER_TURN = 3;
+
+/** A user-role message carrying only tool results, not a fresh prompt. */
+function isToolResultMessage(message: Message): boolean {
+  return (
+    message.role === "user" &&
+    message.content.length > 0 &&
+    message.content.every((block) => block.type === "tool_result")
+  );
+}
+
+/** Count of genuine user prompts in history — the conversation's turn number. */
+function countUserTurns(messages: ReadonlyArray<Message>): number {
+  let turns = 0;
+  for (const message of messages) {
+    if (message.role === "user" && !isToolResultMessage(message)) turns++;
+  }
+  return turns;
+}
+
+const stop: PluginHookFn<StopContext> = async (ctx) => {
+  // Only re-title at a genuine turn end. A `"continue"` decision means an
+  // earlier hook is re-querying the model (e.g. an empty-response nudge), so
+  // defer to the eventual terminal stop.
+  if (ctx.decision !== "stop") return;
+
+  if (getConfig().conversations.skipAutoRetitling) return;
+
+  if (countUserTurns(ctx.messages) !== SECOND_PASS_USER_TURN) return;
+
+  const { conversationId } = ctx;
+  // Deferred to a later macrotask so the just-completed turn lands first. The
+  // hook fires at the stop boundary, before the loop appends the turn's
+  // assistant reply to history and emits `message_complete` (which persists
+  // it). The service regenerates from the most recent stored messages, so it
+  // must run after the reply is persisted to reflect it. The service is itself
+  // fire-and-forget and re-checks replaceability, owning provider resolution,
+  // persistence, and the resulting broadcast.
+  setTimeout(() => {
+    queueRegenerateConversationTitle({ conversationId });
+  }, 0);
+};
+
+export default stop;

package/src/plugins/defaults/title-generate/hooks/user-prompt-submit.ts

@@ -0,0 +1,35 @@
+/**
+ * Default `user-prompt-submit` hook: kicks off conversation-title generation
+ * from the submitted prompt.
+ *
+ * Title generation is a self-contained side effect that only needs the user's
+ * prompt as context, so it belongs at the prompt-submit boundary rather than
+ * threaded through the agent loop. The hook is a pure trigger — it schedules
+ * the work and returns; persistence and the resulting
+ * `conversation_title_updated` / `sync_changed` broadcast are owned by the
+ * title service (see `memory/conversation-title-service.ts`).
+ */
+
+import type {
+  PluginHookFn,
+  UserPromptSubmitContext,
+} from "@vellumai/plugin-api";
+
+import { queueGenerateConversationTitle } from "../../../../memory/conversation-title-service.js";
+
+const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+  // Deferred to a later macrotask so the main agent-loop LLM request is
+  // issued first; on strict single-slot provider configs this keeps the
+  // background title call from claiming the rate-limit slot ahead of the
+  // user-visible response. The title service is itself fire-and-forget and
+  // re-checks title replaceability before making any LLM call, so an
+  // already-titled conversation incurs no generation.
+  setTimeout(() => {
+    queueGenerateConversationTitle({
+      conversationId: ctx.conversationId,
+      userMessage: ctx.prompt,
+    });
+  }, 0);
+};
+
+export default userPromptSubmit;

package/src/plugins/defaults/title-generate/package.json

@@ -1,7 +1,7 @@
 {
   "name": "default-title-generate",
   "version": "1.0.0",
-  "description": "First-party default plugin wrapping the assistant's built-in title-generate pipeline with a passthrough implementation.",
+  "description": "First-party default plugin that triggers conversation-title generation from the user-prompt-submit hook.",
   "private": true,
   "license": "MIT",
   "type": "module",

package/src/plugins/defaults/title-generate/register.ts

@@ -1,11 +1,17 @@
 /**
- * Default `titleGenerate` pipeline plugin.
+ * Default `title-generate` plugin.
  *
- * Declares no middleware — the terminal handler in `./terminal.ts` is wired in
- * as the pipeline's `terminal` argument by the `runPipeline` call site in
- * `daemon/conversation-agent-loop.ts`. This plugin exists purely to negotiate
- * the `titleGenerateApi` capability so bootstrap has a record that the
- * assistant runtime exposes this pipeline.
+ * Contributes two hooks, both pure triggers that delegate the title work to
+ * the service (`memory/conversation-title-service.ts`):
+ *
+ * - `user-prompt-submit` (`./hooks/user-prompt-submit.ts`) — first-pass title
+ *   generation from the submitted prompt.
+ * - `stop` (`./hooks/stop.ts`) — second-pass regeneration once the
+ *   conversation reaches its third user turn, for a title that reflects the
+ *   established topic.
+ *
+ * Persistence and the resulting `conversation_title_updated` / `sync_changed`
+ * broadcast are owned by the title service.
  *
  * Registered via a side-effect import from
  * `daemon/external-plugins-bootstrap.ts` so it is present in the registry
@@ -13,23 +19,17 @@
  */
 
 import { type Plugin } from "../../types.js";
+import stop from "./hooks/stop.js";
+import userPromptSubmit from "./hooks/user-prompt-submit.js";
 import pkg from "./package.json" with { type: "json" };
 
-/**
- * Default titleGenerate plugin. Declares no middleware — it exists purely
- * to negotiate the `titleGenerateApi` capability so bootstrap has a record
- * that the assistant runtime exposes this pipeline.
- *
- * The terminal handler (`./terminal.ts`) is supplied at the call site in
- * `conversation-agent-loop.ts` rather than through `middleware.titleGenerate`,
- * because a default middleware would short-circuit user-registered middleware
- * by always running first in onion order. Keeping the terminal outside the
- * middleware chain lets user plugins observe/transform/short-circuit the
- * call without competing with an assistant-owned default middleware.
- */
 export const defaultTitleGeneratePlugin: Plugin = {
   manifest: {
     name: pkg.name,
     version: pkg.version,
   },
+  hooks: {
+    "user-prompt-submit": userPromptSubmit,
+    stop,
+  },
 };

package/src/plugins/defaults/tool-error/hooks/post-tool-use.ts

@@ -0,0 +1,118 @@
+/**
+ * Default `post-tool-use` hook: when a tool result carries `is_error`, set
+ * `additionalContext` with a system-notice that coaches the model to either
+ * retry with corrected parameters (for recoverable errors) or report the
+ * failure to the user (for unrecoverable ones).
+ *
+ * The coaching is delivered via `additionalContext`, not by mutating the tool
+ * result's `content`. The loop appends it to the provider-bound history as a
+ * separate block after the tool_result event is emitted, so the model sees the
+ * guidance while the client-facing and persisted tool output stay the tool's
+ * actual result. This mirrors how Claude Code (`additionalContext`) and Codex
+ * (`additional_contexts`) surface PostToolUse feedback as separate context
+ * rather than rewriting the tool response.
+ *
+ * The coaching is bounded per tool: once a single tool has failed
+ * `MAX_CONSECUTIVE_ERROR_NUDGES` times in a row the notice is dropped — the
+ * error is likely not something the model can fix on its own, and continuing
+ * to coach a retry only burns tokens. The consecutive-failure count is derived
+ * from the conversation history (the trailing run of error results for this
+ * tool name, plus the current one) rather than a loop-held counter, so the
+ * guard survives mid-run compaction rewriting the history array. A successful
+ * result for the tool resets its streak.
+ */
+
+import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+
+import type { Message } from "../../../../providers/types.js";
+
+/**
+ * Canonical tool-error coaching text. Kept as a module-level constant so tests
+ * and plugins that wrap the default can match it without duplicating the
+ * string.
+ *
+ * This is shown to the model as provider-only context, not the user. Edits
+ * here affect retry behavior but not end-user UX directly.
+ */
+export const TOOL_ERROR_NUDGE_TEXT =
+  "<system_notice>This tool call returned an error. If the error looks recoverable (e.g. missing or invalid parameters), fix the parameters and retry. If the error is clearly unrecoverable (e.g. a service is down, a resource does not exist, or a permission is permanently denied), report it to the user.</system_notice>";
+
+/**
+ * Number of back-to-back failures of a single tool to coach before giving up.
+ * Coaching fires on the 1st through Nth consecutive failure and is dropped from
+ * the (N+1)th onward.
+ */
+const MAX_CONSECUTIVE_ERROR_NUDGES = 3;
+
+/** Map every `tool_use` block id in history to the tool name it invoked. */
+function toolNamesById(messages: ReadonlyArray<Message>): Map<string, string> {
+  const names = new Map<string, string>();
+  for (const message of messages) {
+    if (message.role !== "assistant") continue;
+    for (const block of message.content) {
+      if (block.type === "tool_use") names.set(block.id, block.name);
+    }
+  }
+  return names;
+}
+
+/**
+ * Trailing run of consecutive error results for `toolName` already in history.
+ * Walks the tool's results in chronological order and counts back from the most
+ * recent until a successful result breaks the streak. The current result is not
+ * yet in history, so callers add it themselves.
+ */
+function priorConsecutiveErrors(
+  messages: ReadonlyArray<Message>,
+  toolName: string,
+  namesById: ReadonlyMap<string, string>,
+): number {
+  const isErrorByOrder: boolean[] = [];
+  for (const message of messages) {
+    if (message.role !== "user") continue;
+    for (const block of message.content) {
+      if (block.type !== "tool_result") continue;
+      if (namesById.get(block.tool_use_id) !== toolName) continue;
+      isErrorByOrder.push(block.is_error === true);
+    }
+  }
+
+  let streak = 0;
+  for (let i = isErrorByOrder.length - 1; i >= 0; i--) {
+    if (!isErrorByOrder[i]) break;
+    streak++;
+  }
+  return streak;
+}
+
+const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+  if (ctx.toolResponse.is_error !== true) return;
+
+  const namesById = toolNamesById(ctx.messages);
+  const toolName = namesById.get(ctx.toolResponse.tool_use_id);
+
+  // Prior failures of this tool plus the current one. An unresolved name (the
+  // current turn's tool_use is always in history, so this is defensive) falls
+  // back to coaching this lone failure.
+  const consecutiveErrors =
+    (toolName === undefined
+      ? 0
+      : priorConsecutiveErrors(ctx.messages, toolName, namesById)) + 1;
+
+  if (consecutiveErrors > MAX_CONSECUTIVE_ERROR_NUDGES) {
+    ctx.logger.info(
+      {
+        plugin: "tool-error",
+        toolName,
+        toolUseId: ctx.toolResponse.tool_use_id,
+        consecutiveErrors,
+      },
+      "Skipping tool-error coaching after repeated consecutive failures",
+    );
+    return;
+  }
+
+  ctx.additionalContext = TOOL_ERROR_NUDGE_TEXT;
+};
+
+export default postToolUse;

package/src/plugins/defaults/tool-error/package.json

@@ -1,7 +1,7 @@
 {
   "name": "default-tool-error",
   "version": "1.0.0",
-  "description": "First-party default plugin wrapping the assistant's built-in tool-error pipeline with a passthrough implementation.",
+  "description": "First-party default plugin contributing a post-tool-use hook that coaches the model to retry or report a failed tool call.",
   "private": true,
   "license": "MIT",
   "type": "module",