@librechat/agents 3.7.7 → 3.7.9

package/src/agents/AgentContext.ts

@@ -50,7 +50,9 @@ import {
   Providers,
 } from '@/common';
 import { isTokenCounterCacheCompatible } from '@/llm/tokenCounterCacheCompatibility';
+import { snapshotCompactionSemanticIndex } from '@/summarization/semanticIndex';
 import { createExactTokenCountCache } from '@/llm/contextPressureMeter';
+import { buildSummaryCarrierText } from '@/summarization/shared';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { apportionTokenCounts } from '@/utils/tokens';
 import { isThinkingEnabled } from '@/llm/request';
@@ -74,6 +76,14 @@ type ProgrammaticToolInstructionTarget = {
   executesDirectly: boolean;
 };
 
+/**
+ * Consecutive summarization attempts that may return no usable summary before
+ * the run stops asking. Every such attempt spends a full model call over the
+ * whole history and leaves the message set exactly as it was, so the cap
+ * bounds spend as much as it bounds the compaction loop.
+ */
+const MAX_SUMMARIZATION_FAILURES = 3;
+
 /**
  * Encapsulates agent-specific state that can vary between agents in a multi-agent system
  */
@@ -108,6 +118,7 @@ export class AgentContext {
       discoveredTools,
       summarizationEnabled,
       summarizationConfig,
+      compactionSemanticIndex,
       initialSummary,
       contextPruningConfig,
       maxToolResultChars,
@@ -141,11 +152,18 @@ export class AgentContext {
       discoveredTools,
       summarizationEnabled,
       summarizationConfig,
+      compactionSemanticIndex,
       contextPruningConfig,
       maxToolResultChars,
     });
 
-    agentContext._sourceInputs = agentConfig;
+    agentContext._sourceInputs =
+      compactionSemanticIndex == null
+        ? agentConfig
+        : {
+          ...agentConfig,
+          compactionSemanticIndex: agentContext.compactionSemanticIndex,
+        };
     agentContext.subagentConfigs = subagentConfigs;
     agentContext.maxSubagentDepth = maxSubagentDepth;
     /**
@@ -346,6 +364,8 @@ export class AgentContext {
   summarizationEnabled?: boolean;
   /** Summarization runtime settings used by graph pruning hooks */
   summarizationConfig?: t.SummarizationConfig;
+  /** Host-supplied advisory guidance consumed only when compaction runs. */
+  compactionSemanticIndex?: t.CompactionSemanticIndex;
   /** Current summary text produced by the summarize node, integrated into system message */
   private summaryText?: string;
   /** Token count of the current summary (tracked for token accounting) */
@@ -376,6 +396,13 @@ export class AgentContext {
    * Summarization is allowed to fire again only when new messages appear.
    */
   private _lastSummarizationMsgCount: number = 0;
+  /**
+   * Consecutive summarization attempts that produced no usable summary.
+   * An empty or failed summary leaves the message set exactly as it was, so
+   * the next prune cycle would ask again on identical state. Cleared by
+   * `setSummary` and by `reset()`.
+   */
+  private _summarizationFailures: number = 0;
   /**
    * Forced compactions performed after a provider rejected a prompt as too
    * large. Bounds the recovery loop so a model that keeps refusing cannot
@@ -430,6 +457,7 @@ export class AgentContext {
     discoveredTools,
     summarizationEnabled,
     summarizationConfig,
+    compactionSemanticIndex,
     contextPruningConfig,
     maxToolResultChars,
   }: {
@@ -456,6 +484,7 @@ export class AgentContext {
     discoveredTools?: string[];
     summarizationEnabled?: boolean;
     summarizationConfig?: t.SummarizationConfig;
+    compactionSemanticIndex?: t.CompactionSemanticIndex;
     contextPruningConfig?: t.ContextPruningConfig;
     maxToolResultChars?: number;
   }) {
@@ -495,6 +524,11 @@ export class AgentContext {
     this.useLegacyContent = useLegacyContent ?? false;
     this.summarizationEnabled = summarizationEnabled;
     this.summarizationConfig = summarizationConfig;
+    if (compactionSemanticIndex != null) {
+      this.compactionSemanticIndex = snapshotCompactionSemanticIndex(
+        compactionSemanticIndex
+      );
+    }
     this.contextPruningConfig = contextPruningConfig;
     this.maxToolResultChars = maxToolResultChars;
 
@@ -934,11 +968,7 @@ export class AgentContext {
   private buildSummaryHumanMessage(
     promptCacheProvider: PromptCacheProvider | undefined
   ): HumanMessage {
-    const wrappedSummary =
-      '<summary>\n' +
-      (this.summaryText as string) +
-      '\n</summary>\n\n' +
-      'This is your own checkpoint: you wrote it to preserve context after compaction. Pick up where you left off based on the summary above. Do not repeat prior tasks, information or acknowledge this checkpoint message directly.';
+    const wrappedSummary = buildSummaryCarrierText(this.summaryText as string);
 
     if (promptCacheProvider !== Providers.ANTHROPIC) {
       return new HumanMessage(wrappedSummary);
@@ -1209,6 +1239,7 @@ export class AgentContext {
     this.summaryTokenCount = this._durableSummaryTokenCount;
     this.summaryPrecedesMessages = this.durableSummaryPrecedesMessages;
     this._lastSummarizationMsgCount = 0;
+    this._summarizationFailures = 0;
     this.lastCallUsage = undefined;
     this.totalTokensFresh = false;
     this.restoreContextBudgetAfterOverflow();
@@ -1478,6 +1509,7 @@ export class AgentContext {
     this._durableSummaryTokenCount = tokenCount;
     this.durableSummaryPrecedesMessages = this.summaryPrecedesMessages;
     this._summaryVersion += 1;
+    this._summarizationFailures = 0;
     this.systemRunnableStale = true;
     this.pruneMessages = undefined;
   }
@@ -1547,6 +1579,31 @@ export class AgentContext {
     this._lastSummarizationMsgCount = msgCount;
   }
 
+  /**
+   * Records a summarization attempt that produced no usable summary — an
+   * empty model response, or a provider failure the run declined to paper
+   * over with a metadata stub. Cleared by the next successful summary.
+   */
+  recordSummarizationFailure(): void {
+    this._summarizationFailures += 1;
+  }
+
+  get summarizationFailures(): number {
+    return this._summarizationFailures;
+  }
+
+  /**
+   * True once consecutive no-progress attempts reach {@link MAX_SUMMARIZATION_FAILURES}.
+   * A summarizer that has returned nothing this many times in a row will keep
+   * returning nothing: each empty result leaves the history unchanged, so the
+   * next prune cycle re-triggers on the same state and the run burns its
+   * recursion budget on empty summary steps. Summarization stays off for the
+   * remainder of the run; `reset()` restores it for the next one.
+   */
+  get summarizationExhausted(): boolean {
+    return this._summarizationFailures >= MAX_SUMMARIZATION_FAILURES;
+  }
+
   get overflowRecoveryAttempts(): number {
     return this._overflowRecoveryAttempts;
   }

package/src/common/constants.ts

@@ -20,6 +20,14 @@ export const DEFAULT_TOOL_TOKEN_MULTIPLIER = 1.4;
  */
 export const DEFAULT_MAX_SEALS = 8;
 
+/**
+ * Default ceiling on Stop-hook continuations within one Run. A blocking Stop
+ * hook can keep a naturally terminal run warm by injecting another user turn;
+ * the ceiling prevents a faulty hook or continuously arriving input from
+ * keeping one processStream call alive forever.
+ */
+export const DEFAULT_MAX_STOP_CONTINUATIONS = 8;
+
 /**
  * Per-hook timeout for `PreemptBoundary`, deliberately far above
  * `DEFAULT_HOOK_TIMEOUT_MS`. A host drain has already popped its queue and
@@ -42,3 +50,14 @@ export const ACTIVITY_LABEL_RUN_NAME = 'StepLabel';
 export const REASONING_LABEL_RUN_NAME = 'ReasoningLabel';
 export const ACTIVITY_PHASE_RUN_NAME = 'MultiStepLabel';
 export const ACTIVITY_PHASE_LABEL_RUN_NAME = 'MultiStepLabelGeneration';
+
+/** Shared admission and rendering bounds for compaction navigation hints. */
+export const COMPACTION_SEMANTIC_INDEX_LIMITS = Object.freeze({
+  maxInputEntries: 256,
+  maxEntries: 64,
+  maxEntryChars: 512,
+  maxTotalChars: 4_096,
+  maxInputTextChars: 4_096,
+  maxIdentityChars: 512,
+  maxSourceContentIndex: 4_095,
+} as const);

package/src/graphs/Graph.ts

@@ -153,10 +153,10 @@ import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
 import { SUBAGENT_REPLAY_CONTROLLER } from '@/tools/subagent/SubagentReplay';
 import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
 import { createContextPressureMeter } from '@/llm/contextPressureMeter';
-import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { prepareProviderRequest } from '@/llm/prepareProviderRequest';
 import { createCloudflareCodingToolBundle } from '@/tools/cloudflare';
+import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { providerRequiresStrictAlternation } from '@/llm/providers';
 import { buildSubagentToolParams } from '@/tools/SubagentTool';
 import { initializeLangfuseTracing } from '@/instrumentation';
@@ -164,6 +164,7 @@ import { shouldTriggerSummarization } from '@/summarization';
 import { isRunStepResumeState } from '@/tools/runStepResume';
 import { resolveLocalToolsForBinding } from '@/tools/local';
 import { createSummarizeNode } from '@/summarization/node';
+import { getTruncationStopReason } from '@/llm/truncation';
 import { messagesStateReducer } from '@/messages/reducer';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
@@ -770,6 +771,9 @@ export abstract class Graph<
   contentData: t.RunStep[] = [];
   protected nextContentIndex = 0;
   protected runStepStateRevision = 0;
+  protected stopContinuationCount = 0;
+  protected stopContinuationExecutionId = '';
+  protected streamSegment = 0;
   stepKeyIds: Map<string, string[]> = new Map<string, string[]>();
   contentIndexMap: Map<string, number> = new Map();
   toolCallStepIds: Map<string, string> = new Map();
@@ -899,6 +903,9 @@ export abstract class Graph<
     this.contentData = [];
     this.nextContentIndex = 0;
     this.runStepStateRevision = 0;
+    this.stopContinuationCount = 0;
+    this.stopContinuationExecutionId = '';
+    this.streamSegment = 0;
     this.contentIndexMap = new Map();
     this.stepKeyIds = new Map();
     this.toolCallStepIds.clear();
@@ -1425,6 +1432,21 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * hosts persist it as unfinished rather than complete.
    */
   preemptIncomplete = false;
+  /**
+   * True when `routeMessage` sent a turn to `END` because the last AI
+   * message carries no tool call, AND the provider reports it stopped for
+   * hitting the output token ceiling (`getTruncationStopReason`). Plain-text
+   * and reasoning turns cut off this way carry no tool call for
+   * `assertNotTruncatedToolCall` to catch, so `toolsCondition` reads them as
+   * an ordinary finished turn otherwise — hosts read this flag to persist
+   * the turn as unfinished instead of a silently truncated "complete" answer.
+   *
+   * Deliberately separate from `preemptIncomplete`/`preemptHaltReason`: this
+   * has no interaction with the preempt/seal machinery (in particular the
+   * `preemptHaltReason` check at each model node's entry), so setting it
+   * cannot suppress an unrelated agent's turn in a multi-agent graph.
+   */
+  outputTruncatedIncomplete = false;
   /**
    * `stopReason` from a `PreemptBoundary` hook that halted the turn.
    *
@@ -1521,6 +1543,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.cachedRunMessages = undefined;
     this.cachedDiscoveredTools = undefined;
     this.config = resetIfNotEmpty(this.config, undefined);
+    this.stopContinuationCount = 0;
+    this.stopContinuationExecutionId = '';
+    this.streamSegment = 0;
     if (keepContent !== true) {
       this.contentData = resetIfNotEmpty(this.contentData, []);
       this.nextContentIndex = 0;
@@ -1702,6 +1727,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.preemptEmptyBoundaries = 0;
     this.preemptIncomplete = false;
     this.preemptHaltReason = undefined;
+    this.outputTruncatedIncomplete = false;
   }
 
   /**
@@ -1818,6 +1844,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       version: 1,
       revision: this.runStepStateRevision,
       nextIndex: this.nextContentIndex,
+      stopContinuationCount: this.stopContinuationCount,
+      ...(this.stopContinuationExecutionId === ''
+        ? {}
+        : {
+          stopContinuationExecutionId: this.stopContinuationExecutionId,
+        }),
+      streamSegment: this.streamSegment,
       toolCallSteps: [...this.toolCallStepIds].map(([toolCallId, stepId]) => ({
         toolCallId,
         stepId,
@@ -1837,6 +1870,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
     this.nextContentIndex = state.nextIndex;
     this.runStepStateRevision = state.revision;
+    this.stopContinuationCount = state.stopContinuationCount ?? 0;
+    this.stopContinuationExecutionId =
+      state.stopContinuationExecutionId ?? '';
+    this.streamSegment = state.streamSegment ?? 0;
     for (const { toolCallId, stepId } of state.toolCallSteps) {
       this.toolCallStepIds.set(toolCallId, stepId);
     }
@@ -1871,6 +1908,30 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     return undefined;
   }
 
+  getStopContinuationCount(): number {
+    return this.stopContinuationCount;
+  }
+
+  setStopContinuationCount(count: number): void {
+    this.stopContinuationCount = count;
+  }
+
+  getStopContinuationExecutionId(): string {
+    return this.stopContinuationExecutionId;
+  }
+
+  startStopContinuationExecution(executionId: string): void {
+    this.stopContinuationExecutionId = executionId;
+  }
+
+  getStreamSegment(): number {
+    return this.streamSegment;
+  }
+
+  advanceStreamSegment(): void {
+    this.streamSegment += 1;
+  }
+
   /**
    * Derives the same lane key `dispatchRunStep` stamps as `runStep.agentId`.
    * The multi-agent check gates the lookup because `getAgentContext` signals
@@ -2319,6 +2380,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       metadata.langgraph_node as string,
       metadata.langgraph_step as number,
       checkpointNs,
+      this.streamSegment,
     ];
 
     return keyList;
@@ -2801,9 +2863,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       provider,
       clientOptions,
       tools,
-      isDeferred: makeIsDeferred(
-        agentContext.getEffectiveToolDefinitions()
-      ),
+      isDeferred: makeIsDeferred(agentContext.getEffectiveToolDefinitions()),
     });
   }
 
@@ -3030,9 +3090,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           messagesToRefine.length > 0;
 
         if (hasPrunedMessages) {
-          const shouldSkip = agentContext.shouldSkipSummarization(
-            messages.length
-          );
+          const shouldSkip =
+            agentContext.summarizationExhausted ||
+            agentContext.shouldSkipSummarization(messages.length);
           const triggerResult =
             !shouldSkip &&
             shouldTriggerSummarization({
@@ -3089,6 +3149,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                 messageCount: messages.length,
                 messagesToRefineCount: messagesToRefine.length,
                 contextLength: context.length,
+                summarizationFailures: agentContext.summarizationFailures,
+                summarizationExhausted: agentContext.summarizationExhausted,
               },
               { runId: this.runId, agentId }
             );
@@ -4818,11 +4880,27 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       if (state.summarizationRequest != null) {
         return summarizeNode;
       }
-      return toolsCondition(
+      const decision = toolsCondition(
         state as t.BaseGraphState,
         toolNode,
         this.invokedToolIds
       );
+      /**
+       * `toolsCondition` only looks at `tool_calls` — a plain-text/reasoning
+       * turn cut off by the output token ceiling has none, so it reads as an
+       * ordinary finished turn and routes here to END. Flag it so hosts can
+       * tell a genuinely finished answer from one the model never got to
+       * complete. See `outputTruncatedIncomplete` for why this stays clear
+       * of the preempt/seal halt fields.
+       */
+      if (decision === END) {
+        const { messages } = state as t.BaseGraphState;
+        const lastMessage = messages[messages.length - 1];
+        if (getTruncationStopReason(lastMessage) != null) {
+          this.outputTruncatedIncomplete = true;
+        }
+      }
+      return decision;
     };
 
     const StateAnnotation = Annotation.Root({

package/src/hooks/HookRegistry.ts

@@ -43,7 +43,9 @@ type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
 /**
  * Events whose hooks can change a tool call's input or output. Presence of
  * any of these disables eager tool execution and early completion emission;
- * observation-only events (`PostToolBatch`, `Stop`, telemetry hooks) do not.
+ * hooks that cannot rewrite a tool result (`PostToolBatch`, `Stop`, telemetry
+ * hooks) do not. A Stop hook may continue the Run, but only after every tool
+ * result in the terminal graph segment is already authoritative.
  */
 const RESULT_ALTERING_HOOK_EVENTS = [
   'PreToolUse',

package/src/hooks/executeHooks.ts

@@ -313,6 +313,9 @@ function applyAggregatedResult(
   target.additionalContexts.push(...source.additionalContexts);
   target.injectedMessages.push(...source.injectedMessages);
   target.errors.push(...source.errors);
+  if (source.hasHookFailures === true) {
+    target.hasHookFailures = true;
+  }
   if (source.decision != null) {
     applyToolDecision(target, source.decision, source.reason);
   }
@@ -347,6 +350,19 @@ function combineAggregatedResults(
   return combined;
 }
 
+/** Deterministically fold results from serialized hook phases. */
+export function mergeAggregatedHookResults(
+  ...results: Array<AggregatedHookResult | undefined>
+): AggregatedHookResult | undefined {
+  let combined: AggregatedHookResult | undefined;
+  for (const result of results) {
+    if (result != null) {
+      combined = combineAggregatedResults(combined, result);
+    }
+  }
+  return combined;
+}
+
 function createPendingApprovalReplay(
   approvalResult: AggregatedHookResult,
   pendingApproval: AggregatedHookResult | undefined,
@@ -377,6 +393,7 @@ function fold(outcomes: readonly HookOutcome[]): {
   for (const outcome of outcomes) {
     const isOnceMatcher = outcome.matcher.once === true;
     if (outcome.error !== null) {
+      aggregated.hasHookFailures = true;
       if (outcome.matcher.internal !== true) {
         aggregated.errors.push(outcome.error);
       }
@@ -455,8 +472,9 @@ function fold(outcomes: readonly HookOutcome[]): {
  * ## Internal matchers
  *
  * A matcher with `internal: true` is excluded from both the `errors` array
- * and the logger output. Use it for infrastructure hooks whose failures
- * should not pollute user-visible diagnostics.
+ * and the logger output. `hasHookFailures` still records that the call was
+ * not fully successful, so fail-closed infrastructure boundaries can reject
+ * without exposing the suppressed diagnostic.
  *
  * ## Once semantics — atomic at-most-once
  *

package/src/hooks/index.ts

@@ -9,7 +9,11 @@
 // `StandardGraph.createCallModel` (PreemptBoundary).
 export { HookRegistry } from './HookRegistry';
 export type { HookHaltSignal } from './HookRegistry';
-export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
+export {
+  executeHooks,
+  mergeAggregatedHookResults,
+  DEFAULT_HOOK_TIMEOUT_MS,
+} from './executeHooks';
 /**
  * Feature probe for hosts: hook outputs support `injectedMessages`
  * (per-message graph-state injection at the `PostToolBatch` boundary).
@@ -28,6 +32,11 @@ export const HOOK_INJECTED_MESSAGES_CAPABLE = true;
  * the user as a dead button rather than as an unsupported feature.
  */
 export const HOOK_PREEMPT_BOUNDARY_CAPABLE = true;
+/**
+ * Feature probe for hosts: a blocking `Stop` hook can inject queued messages
+ * and continue within the same `Run.processStream` lifecycle.
+ */
+export const HOOK_STOP_CONTINUATION_CAPABLE = true;
 export {
   matchesQuery,
   hasNestedQuantifier,
@@ -71,6 +80,7 @@ export type {
   SubagentStartHookInput,
   SubagentStopHookInput,
   StopHookInput,
+  StopFinalizeHookInput,
   StopFailureHookInput,
   PreCompactHookInput,
   PostCompactHookInput,
@@ -85,6 +95,7 @@ export type {
   SubagentStartHookOutput,
   SubagentStopHookOutput,
   StopHookOutput,
+  StopFinalizeHookOutput,
   StopFailureHookOutput,
   PreCompactHookOutput,
   PostCompactHookOutput,

package/src/hooks/types.ts

@@ -22,6 +22,7 @@ export const HOOK_EVENTS = [
   'SubagentStart',
   'SubagentStop',
   'Stop',
+  'StopFinalize',
   'StopFailure',
   'PreCompact',
   'PostCompact',
@@ -209,7 +210,34 @@ export interface StopHookInput extends BaseHookInput {
   hook_event_name: 'Stop';
   messages: BaseMessage[];
   stopReason?: string;
+  /** True after this hook has already kept the current Run warm once. */
   stopHookActive: boolean;
+  /** Number of terminal continuations already admitted in this Run. */
+  continuationCount: number;
+  /**
+   * Remaining continuations the SDK can honor. A host that durably claims
+   * queued work MUST seal admission instead when this reaches zero.
+   */
+  continuationBudgetRemaining: number;
+}
+
+/**
+ * Serialized terminal admission phase. Unlike ordinary `Stop` hooks (which
+ * execute in parallel), this fires after their outputs have been folded so a
+ * durable host can make one final claim-or-seal decision with full knowledge
+ * of whether another hook already kept the Run warm.
+ */
+export interface StopFinalizeHookInput extends BaseHookInput {
+  hook_event_name: 'StopFinalize';
+  messages: BaseMessage[];
+  stopReason?: string;
+  stopHookActive: boolean;
+  continuationCount: number;
+  continuationBudgetRemaining: number;
+  /** A regular Stop hook already supplied a valid warm continuation. */
+  continuationPlanned: boolean;
+  /** A halt reason or Stop output forbids another graph segment. */
+  continuationPrevented: boolean;
 }
 
 export interface StopFailureHookInput extends BaseHookInput {
@@ -259,6 +287,7 @@ export type HookInput =
   | SubagentStartHookInput
   | SubagentStopHookInput
   | StopHookInput
+  | StopFinalizeHookInput
   | StopFailureHookInput
   | PreCompactHookInput
   | PostCompactHookInput;
@@ -276,6 +305,7 @@ export type HookInputByEvent = {
   SubagentStart: SubagentStartHookInput;
   SubagentStop: SubagentStopHookInput;
   Stop: StopHookInput;
+  StopFinalize: StopFinalizeHookInput;
   StopFailure: StopFailureHookInput;
   PreCompact: PreCompactHookInput;
   PostCompact: PostCompactHookInput;
@@ -298,10 +328,11 @@ export interface BaseHookOutput {
    * mid-run steering message). Accumulated across hooks in registration
    * order.
    *
-   * Consumed at exactly two dispatch sites, both of which run the same
-   * converter so the emitted shapes cannot drift: `PostToolBatch` (the tool
-   * boundary) and `PreemptBoundary` (a cooperative mid-generation seal).
-   * Every other event ignores the field.
+   * Consumed at three dispatch sites, all of which run the same converter so
+   * the emitted shapes cannot drift: `PostToolBatch` (the tool boundary),
+   * `PreemptBoundary` (a cooperative mid-generation seal), and a blocking
+   * `Stop` hook (terminal Run continuation). Every other event ignores the
+   * field.
    */
   injectedMessages?: InjectedMessage[];
   /** True to prevent the next model turn. Any hook can set this. */
@@ -435,10 +466,18 @@ export interface SubagentStartHookOutput extends BaseHookOutput {
 export type SubagentStopHookOutput = BaseHookOutput;
 
 export interface StopHookOutput extends BaseHookOutput {
+  /**
+   * `block` keeps a naturally terminal Run warm only when the output also
+   * supplies non-empty `injectedMessages` or `additionalContext`. The SDK
+   * starts another graph segment inside the same `processStream` call; no
+   * RunStart/UserPromptSubmit hooks or terminal cleanup occur between them.
+   */
   decision?: StopDecision;
   reason?: string;
 }
 
+export type StopFinalizeHookOutput = StopHookOutput;
+
 export type StopFailureHookOutput = BaseHookOutput;
 
 export type PreCompactHookOutput = BaseHookOutput;
@@ -458,6 +497,7 @@ export type HookOutputByEvent = {
   SubagentStart: SubagentStartHookOutput;
   SubagentStop: SubagentStopHookOutput;
   Stop: StopHookOutput;
+  StopFinalize: StopFinalizeHookOutput;
   StopFailure: StopFailureHookOutput;
   PreCompact: PreCompactHookOutput;
   PostCompact: PostCompactHookOutput;
@@ -476,6 +516,7 @@ export type HookOutput =
   | SubagentStartHookOutput
   | SubagentStopHookOutput
   | StopHookOutput
+  | StopFinalizeHookOutput
   | StopFailureHookOutput
   | PreCompactHookOutput
   | PostCompactHookOutput;
@@ -593,6 +634,8 @@ export interface AggregatedHookResult {
    * `preventContinuation` do not overwrite the reason.
    */
   stopReason?: string;
+  /** True when any hook failed, including internal hooks with hidden diagnostics. */
+  hasHookFailures?: true;
   /** Error messages from hooks that threw; always present (possibly empty). */
   errors: string[];
 }