@librechat/agents 3.2.61 → 3.2.63

package/dist/types/hooks/HookRegistry.d.ts

@@ -108,6 +108,16 @@ export declare class HookRegistry {
      * halt state. No-op when no signal exists for that session.
      */
     clearHaltSignal(sessionId: string): void;
+    /**
+     * True when any registered hook can alter a tool result before or after
+     * execution (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`). Eager
+     * tool execution and early completion emission gate on this instead of
+     * registry presence, so observation-only registries (e.g. a
+     * `PostToolBatch` steering drain) keep those fast paths. With
+     * `sessionId`, checks global + that session; without it, conservatively
+     * scans every session bucket.
+     */
+    hasResultAlteringHooks(sessionId?: string): boolean;
     /** True if at least one matcher exists for `event` (global + session). */
     hasHookFor(event: HookEvent, sessionId?: string): boolean;
     private ensureSessionBucket;

package/dist/types/hooks/index.d.ts

@@ -1,6 +1,13 @@
 export { HookRegistry } from './HookRegistry';
 export type { HookHaltSignal } from './HookRegistry';
 export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
+/**
+ * Feature probe for hosts: hook outputs support `injectedMessages`
+ * (per-message graph-state injection at the `PostToolBatch` boundary).
+ * Hosts must gate drain-style hooks on this so a queued message can never
+ * be consumed by an SDK version that would silently drop it.
+ */
+export declare const HOOK_INJECTED_MESSAGES_CAPABLE = true;
 export { matchesQuery, hasNestedQuantifier, MAX_PATTERN_LENGTH, MAX_CACHE_SIZE, } from './matchers';
 export { createToolPolicyHook } from './createToolPolicyHook';
 export type { ToolPolicyMode, ToolPolicyConfig } from './createToolPolicyHook';

package/dist/types/hooks/types.d.ts

@@ -1,4 +1,5 @@
 import type { BaseMessage } from '@langchain/core/messages';
+import type { InjectedMessage } from '@/types/tools';
 /**
  * Closed set of hook lifecycle events supported by the hooks system.
  *
@@ -107,7 +108,9 @@ export interface PostToolBatchEntry {
  *
  * Order: fires AFTER all per-tool PostToolUse / PostToolUseFailure hooks
  * for the same batch have completed, BEFORE the next model call. Pass an
- * `additionalContext` to inject context for that next model turn.
+ * `additionalContext` to inject context for that next model turn, or
+ * `injectedMessages` to inject standalone per-message user speech (e.g.
+ * mid-run steering) that must not be consolidated with hook context.
  */
 export interface PostToolBatchHookInput extends BaseHookInput {
     hook_event_name: 'PostToolBatch';
@@ -191,6 +194,18 @@ export type HookInputByEvent = {
 export interface BaseHookOutput {
     /** Context string to inject into the conversation. Accumulated across hooks. */
     additionalContext?: string;
+    /**
+     * Messages to inject into graph state, one `HumanMessage` per entry
+     * (converted via `ToolNode.convertInjectedMessages`, which preserves
+     * `role`/`source`/`isMeta` in `additional_kwargs`). Unlike
+     * `additionalContext` — which is consolidated across hooks into a single
+     * system-flavored message — each entry keeps its own identity and role,
+     * making this the channel for injecting verbatim user speech (e.g. a
+     * mid-run steering message). Accumulated across hooks in registration
+     * order. Currently consumed only at the `PostToolBatch` dispatch site;
+     * other events ignore the field.
+     */
+    injectedMessages?: InjectedMessage[];
     /** True to prevent the next model turn. Any hook can set this. */
     preventContinuation?: boolean;
     /** Reason reported alongside `preventContinuation`. */
@@ -418,6 +433,8 @@ export interface AggregatedHookResult {
     updatedOutput?: unknown;
     /** Accumulated `additionalContext` strings from every hook, in order. */
     additionalContexts: string[];
+    /** Accumulated `injectedMessages` from every hook, in registration order. */
+    injectedMessages: InjectedMessage[];
     /** True if any hook returned `preventContinuation`. */
     preventContinuation?: boolean;
     /**

package/dist/types/llm/bedrock/index.d.ts

@@ -52,6 +52,10 @@ export interface CustomChatBedrockConverseInput extends ChatBedrockConverseInput
      * on; use `'5m'` for any model that rejects it.
      */
     promptCacheTtl?: PromptCacheTtl;
+    /**
+     * Minimum delay in milliseconds between visible streamed content deltas.
+     */
+    _lc_stream_delay?: number;
     /**
      * Guardrail configuration for Converse and ConverseStream invocations.
      * `streamProcessingMode` is only used by ConverseStream.
@@ -89,6 +93,7 @@ export interface CustomChatBedrockConverseCallOptions {
     guardrailConfig?: CustomGuardrailConfiguration;
 }
 export declare class CustomChatBedrockConverse extends ChatBedrockConverse {
+    _lc_stream_delay: number;
     /**
      * Whether to insert Bedrock prompt cache checkpoints when available.
      */

package/dist/types/llm/openai/index.d.ts

@@ -20,10 +20,23 @@ type LibreChatOpenAIFields = t.ChatOpenAIFields & {
     includeReasoningContent?: boolean;
     includeReasoningDetails?: boolean;
     convertReasoningDetailsToContent?: boolean;
+    promptCacheExplicit?: boolean;
+    safety_identifier?: string;
 };
 type LibreChatAzureOpenAIFields = t.AzureOpenAIInput & {
     _lc_stream_delay?: number;
+    promptCacheExplicit?: boolean;
+    safety_identifier?: string;
 };
+/** @internal */
+export declare function addChatCacheBreakpoints(messages: OpenAIClient.Chat.Completions.ChatCompletionMessageParam[]): OpenAIClient.Chat.Completions.ChatCompletionMessageParam[];
+/** @internal */
+export declare function addResponseCacheBreakpoints(input: OpenAIClient.Responses.ResponseCreateParams['input']): OpenAIClient.Responses.ResponseCreateParams['input'];
+/** @internal */
+export declare function shouldIncludeEncryptedReasoning(model: string, params: {
+    store?: boolean | null;
+    reasoning?: unknown;
+}): boolean;
 export declare function emitStreamChunkCallback(chunk: ChatGenerationChunk, runManager?: CallbackManagerForLLMRun): Promise<void>;
 /**
  * Formats a tool in either OpenAI format, or LangChain structured tool format
@@ -64,6 +77,12 @@ export declare class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptio
     getReasoningParams(options?: this['ParsedCallOptions']): OpenAIClient.Reasoning | undefined;
     protected _getReasoningParams(options?: this['ParsedCallOptions']): OpenAIClient.Reasoning | undefined;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
+    /**
+     * Raw variant that skips scalar-metadata de-duplication. Used by subclasses
+     * (e.g. `ChatOpenRouter`) that read `finish_reason` as a control signal and
+     * must de-duplicate only after their own finalization.
+     */
+    protected _streamRawResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
 export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
     _lc_stream_delay?: number;

package/dist/types/llm/openai/streamMetadata.d.ts

@@ -0,0 +1,16 @@
+import type { ChatGenerationChunk } from '@langchain/core/outputs';
+/** Per-completion-index set of scalar fields already emitted this stream. */
+export type SeenScalarMetadata = Map<number, Set<string>>;
+/**
+ * Strip scalar `response_metadata`/`generationInfo` fields that have already
+ * appeared on an earlier chunk of the same completion (tracked in `seen`),
+ * keeping the first occurrence so the aggregated message still carries the
+ * value once. Scoped per completion index so multi-choice (`n > 1`) responses,
+ * which `_generate` aggregates separately, keep each choice's own metadata.
+ *
+ * Deletes from a shallow clone rather than in place: providers such as
+ * `ChatDeepSeek` split one raw chunk into several synthetic pieces that share
+ * the same `response_metadata`/`generationInfo` objects, so mutating in place
+ * would strip fields from sibling chunks that were already emitted.
+ */
+export declare function dropRepeatedScalarMetadata(chunk: ChatGenerationChunk, seen: SeenScalarMetadata): void;

package/dist/types/messages/prune.d.ts

@@ -61,9 +61,10 @@ export type PruneMessagesParams = {
     usageMetadata?: Partial<UsageMetadata>;
     startType?: ReturnType<BaseMessage['getType']>;
     /**
-     * Usage from the most recent LLM call only (not accumulated).
-     * When provided, calibration uses this instead of usageMetadata
-     * to avoid inflated ratios from N×cacheRead accumulation.
+     * Fallback usage from the most recent LLM call only (not accumulated).
+     * Calibration prefers the provider's raw `usageMetadata.input_tokens`
+     * when available, because cache detail fields may use non-window
+     * accounting units.
      */
     lastCallUsage?: {
         totalTokens: number;

package/dist/types/tools/ToolNode.d.ts

@@ -369,6 +369,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      *    ToolMessages (appended AFTER to respect provider ordering).
      */
     private dispatchToolEvents;
+    /** Run-scoped so another run's session hooks can't flip this run's gate. */
     private canConsumeEagerEventExecution;
     private takeMatchingEagerEventExecution;
     private resolveEagerEventExecution;

package/dist/types/types/graph.d.ts

@@ -233,6 +233,16 @@ export type StandardGraphInput = {
      * they already flow through the registry's `CHAT_MODEL_END` handler.
      */
     subagentUsageSink?: SubagentUsageSink;
+    /**
+     * True when this graph IS a subagent child run (set by `SubagentExecutor`
+     * when it constructs the child graph). Drives the hook-input `agentId`
+     * subagent-scope marker: hook dispatches from this graph's tool nodes
+     * carry `agentId` so run-scoped host hooks — which fire for child scopes
+     * too, because children inherit the parent's `run_id` — can tell child
+     * scope from the top level. Top-level graphs leave this unset and their
+     * hook inputs carry only `executingAgentId`.
+     */
+    subagentScope?: boolean;
 };
 export type GraphEdge = {
     /** Agent ID, use a list for multiple sources */

package/dist/types/types/llm.d.ts

@@ -28,7 +28,7 @@ export type AzureClientOptions = Partial<OpenAIChatInput> & Partial<AzureOpenAII
     deploymentName?: string;
 } & BaseChatModelParams & {
     configuration?: OAIClientOptions;
-};
+} & ManagedRequestOptions;
 /**
  * Controls whether Claude's reasoning content is returned in adaptive
  * thinking responses. Added for Claude Opus 4.7, which omits thinking by
@@ -52,7 +52,13 @@ export type GoogleThinkingConfig = {
     includeThoughts?: boolean;
     thinkingLevel?: 'THINKING_LEVEL_UNSPECIFIED' | 'LOW' | 'MEDIUM' | 'HIGH';
 };
-export type OpenAIClientOptions = ChatOpenAIFields;
+/** GPT-5.6 managed-request passthrough fields, shared by the OpenAI and
+ *  Azure wrappers that both read them. */
+export type ManagedRequestOptions = {
+    promptCacheExplicit?: boolean;
+    safety_identifier?: string;
+};
+export type OpenAIClientOptions = ChatOpenAIFields & ManagedRequestOptions;
 export type AnthropicClientOptions = Omit<AnthropicInput, 'thinking'> & {
     thinking?: ThinkingConfig;
     promptCache?: boolean;
@@ -78,6 +84,10 @@ export type BedrockAnthropicInput = ChatBedrockConverseInput & {
      * server-side, so the default is safe to leave on.
      */
     promptCacheTtl?: PromptCacheTtl;
+    /**
+     * Minimum delay in milliseconds between visible streamed content deltas.
+     */
+    _lc_stream_delay?: number;
 };
 export type BedrockConverseClientOptions = BedrockAnthropicInput;
 export type BedrockAnthropicClientOptions = BedrockAnthropicInput;

package/dist/types/types/tools.d.ts

@@ -482,7 +482,7 @@ export type InjectedMessage = {
     /** When true, the message is framework-internal: not shown in UI, not counted as a user turn */
     isMeta?: boolean;
     /** Origin tag for downstream consumers (UI, pruner, compaction) */
-    source?: 'skill' | 'hook' | 'system';
+    source?: 'skill' | 'hook' | 'system' | 'steer';
     /** Only set when source is 'skill', for compaction preservation */
     skillName?: string;
 };

package/dist/types/utils/tokens.d.ts

@@ -1,5 +1,7 @@
 import type { BaseMessage } from '@langchain/core/messages';
 export type EncodingName = 'o200k_base' | 'claude';
+/** Safety margin for image and document token estimates (5% overestimate). */
+export declare const IMAGE_TOKEN_SAFETY_MARGIN = 1.05;
 /**
  * Extracts image dimensions from the first bytes of a base64-encoded
  * PNG, JPEG, GIF, or WebP without decoding the full image.
@@ -13,6 +15,34 @@ export declare function extractImageDimensions(base64Data: string): {
 export declare function estimateAnthropicImageTokens(width: number, height: number): number;
 /** Estimates image token cost for OpenAI (high detail). */
 export declare function estimateOpenAIImageTokens(width: number, height: number, detail?: string): number;
+/**
+ * Estimates token cost for an image content block.
+ * Extracts dimensions from base64 header when available.
+ * Falls back to Anthropic minimum (1024) when dimensions can't be determined.
+ */
+export declare function estimateImageBlockTokens(block: Record<string, unknown>, encoding: EncodingName): number;
+/**
+ * Estimates token cost for a document/file content block.
+ * Handles both LangChain standard format (`type: 'file'` with `source_type`)
+ * and Anthropic format (`type: 'document'` with `source`).
+ *
+ * - Plain text: tokenized directly via `getTokenCount`.
+ * - Base64 PDF: page count estimated from base64 length × per-page cost.
+ * - URL reference: conservative flat estimate.
+ */
+export declare function estimateDocumentBlockTokens(block: Record<string, unknown>, encoding: EncodingName, getTokenCount: (text: string) => number): number;
+/**
+ * Estimates token cost for a timed-media block (video/audio). Handles Google
+ * `{ type: 'media', mimeType, data|url|fileUri }`, OpenRouter
+ * `{ type: 'video_url' }` / `{ type: 'input_audio' }`, and standard
+ * `{ type: 'video' }` / `{ type: 'audio' }` blocks (payload as `data` base64 or
+ * `Uint8Array`, base64 `url`, or `fileId`). Duration is inferred from encoded
+ * size (providers price by duration, which the block does not carry) at Gemini's
+ * rates; a payload with no size (bare URL / file id) falls back to a ~30s
+ * estimate. Returns 0 for non-timed media (e.g. an image/document `media` block)
+ * so it is never mispriced as video.
+ */
+export declare function estimateTimedMediaBlockTokens(block: Record<string, unknown>): number;
 export declare function encodingForModel(model: string): EncodingName;
 export declare function getTokenCountForMessage(message: BaseMessage, getTokenCount: (text: string) => number, encoding?: EncodingName): number;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.2.61",
+  "version": "3.2.63",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -114,7 +114,7 @@
   "scripts": {
     "prepare": "node husky-setup.js",
     "prepublishOnly": "npm run build",
-    "build": "rm -rf ./dist && tsdown && tsc -p tsconfig.build.json",
+    "build": "tsdown && tsc -p tsconfig.build.json",
     "build:dev": "tsdown",
     "sort-imports": "node scripts/sort-imports.ts",
     "sort-imports:check": "node scripts/sort-imports.ts --check",
@@ -200,7 +200,7 @@
     "format": "prettier --write ."
   },
   "overrides": {
-    "@langchain/openai": "1.5.3",
+    "@langchain/openai": "1.5.5",
     "@browserbasehq/stagehand": {
       "openai": "$openai"
     },
@@ -216,7 +216,7 @@
     "@aws-sdk/client-bedrock-runtime": "^3.1075.0",
     "@langchain/anthropic": "^1.5.1",
     "@langchain/aws": "^1.4.2",
-    "@langchain/core": "^1.2.1",
+    "@langchain/core": "^1.2.2",
     "@langchain/deepseek": "^1.1.3",
     "@langchain/google-common": "2.2.0",
     "@langchain/google-gauth": "2.2.0",
@@ -224,7 +224,7 @@
     "@langchain/google-vertexai": "2.2.0",
     "@langchain/langgraph": "^1.4.6",
     "@langchain/mistralai": "^1.2.0",
-    "@langchain/openai": "1.5.3",
+    "@langchain/openai": "1.5.5",
     "@langchain/textsplitters": "^1.0.1",
     "@langchain/xai": "^1.4.3",
     "@langfuse/langchain": "^5.4.1",
@@ -243,7 +243,7 @@
     "mathjs": "^15.2.0",
     "nanoid": "^3.3.7",
     "okapibm25": "^1.4.1",
-    "openai": "^6.35.0",
+    "openai": "^6.46.0",
     "uuid": "^11.1.1"
   },
   "peerDependencies": {

package/src/__tests__/stream.eagerEventExecution.test.ts

@@ -21,6 +21,13 @@ import {
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
 import { HandlerRegistry } from '@/events';
 import * as events from '@/utils/events';
+import { HookRegistry } from '@/hooks';
+
+function createResultAlteringRegistry(): HookRegistry {
+  const registry = new HookRegistry();
+  registry.register('PreToolUse', { hooks: [async () => ({})] });
+  return registry;
+}
 
 function createGraph(overrides: Partial<StandardGraph> = {}): StandardGraph {
   const runSteps = new Map<string, t.RunStep>();
@@ -3221,9 +3228,50 @@ describe('ChatModelStreamHandler eager event tool execution', () => {
     expect(graph.eagerEventToolCallChunks.size).toBe(0);
   });
 
+  it('does not prestart when parent-run session hooks alter results', async () => {
+    // A subagent child graph has its own runId, but ToolNode executes hooks
+    // under the PARENT run id from `configurable.run_id` ONLY — the prestart
+    // gate must read the same source (a differing metadata run id here is a
+    // deliberate distractor pinning the precedence).
+    const sessionRegistry = new HookRegistry();
+    sessionRegistry.registerSession('parent-run', 'PreToolUse', {
+      hooks: [async () => ({ decision: 'allow' as const })],
+    });
+    const graph = createGraph({
+      runId: 'child-run',
+      hookRegistry: sessionRegistry,
+      config: {
+        configurable: { user_id: 'user_1', run_id: 'parent-run' },
+        metadata: { run_id: 'run_1' },
+      },
+    } as Partial<StandardGraph>);
+    const sessionDispatchSpy = jest.spyOn(events, 'safeDispatchCustomEvent');
+
+    await new ChatModelStreamHandler().handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_calls: [
+            { id: 'call_weather', name: 'weather', args: { city: 'NYC' } },
+          ],
+        } as unknown as t.StreamChunk,
+      },
+      { langgraph_node: 'agent', run_id: 'some-other-run' },
+      graph
+    );
+
+    expect(sessionDispatchSpy).not.toHaveBeenCalledWith(
+      GraphEvents.ON_TOOL_EXECUTE,
+      expect.anything(),
+      expect.anything()
+    );
+    expect(graph.eagerEventToolExecutions.size).toBe(0);
+  });
+
   it('does not prestart when batch-sensitive hooks are configured', async () => {
     const graph = createGraph({
-      hookRegistry: {} as StandardGraph['hookRegistry'],
+      hookRegistry: createResultAlteringRegistry(),
     });
     const dispatchSpy = jest.spyOn(events, 'safeDispatchCustomEvent');
 
@@ -3253,6 +3301,56 @@ describe('ChatModelStreamHandler eager event tool execution', () => {
     expect(graph.eagerEventToolExecutions.size).toBe(0);
   });
 
+  it('prestarts when the registry only has observation hooks (PostToolBatch)', async () => {
+    const observationRegistry = new HookRegistry();
+    observationRegistry.register('PostToolBatch', {
+      hooks: [async () => ({})],
+    });
+    const graph = createGraph({ hookRegistry: observationRegistry });
+    const toolExecuteCalls: t.ToolExecuteBatchRequest[] = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        const batch = data as t.ToolExecuteBatchRequest;
+        toolExecuteCalls.push(batch);
+        batch.resolve([
+          {
+            toolCallId: 'call_weather',
+            status: 'success',
+            content: 'sunny',
+          },
+        ]);
+      });
+
+    await new ChatModelStreamHandler().handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_calls: [
+            {
+              id: 'call_weather',
+              name: 'weather',
+              args: { city: 'NYC' },
+            },
+          ],
+          response_metadata: finalToolCallResponseMetadata,
+        } as unknown as t.StreamChunk,
+      },
+      { langgraph_node: 'agent' },
+      graph
+    );
+
+    expect(toolExecuteCalls).toHaveLength(1);
+    expect(graph.eagerEventToolExecutions.get('call_weather')).toMatchObject({
+      toolCallId: 'call_weather',
+      toolName: 'weather',
+    });
+  });
+
   it('does not buffer streamed chunks when eager execution is disabled', async () => {
     const graph = createGraph({
       eagerEventToolExecution: { enabled: false },
@@ -4418,7 +4516,7 @@ describe('ChatModelStreamHandler eager event tool execution', () => {
 
   it('does not prestart on-arrival sealed calls when batch-sensitive hooks are configured', async () => {
     const graph = createGraph({
-      hookRegistry: {} as StandardGraph['hookRegistry'],
+      hookRegistry: createResultAlteringRegistry(),
     });
     const dispatchSpy = jest.spyOn(events, 'safeDispatchCustomEvent');
 

package/src/common/enum.ts

@@ -140,6 +140,8 @@ export enum ContentTypes {
   SUMMARY = 'summary',
   /** Bedrock */
   REASONING_CONTENT = 'reasoning_content',
+  /** Mid-run user steer persisted inline in an assistant message; replayed as a user turn */
+  STEER = 'steer',
 }
 
 export enum ToolCallTypes {

package/src/graphs/Graph.ts

@@ -870,6 +870,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * {@link t.StandardGraphInput.subagentUsageSink}.
    */
   subagentUsageSink?: t.SubagentUsageSink;
+  /** See {@link t.StandardGraphInput.subagentScope}. */
+  subagentScope: boolean;
 
   constructor({
     runId,
@@ -880,12 +882,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     indexTokenCountMap,
     calibrationRatio,
     subagentUsageSink,
+    subagentScope,
   }: t.StandardGraphInput) {
     super();
     this.runId = runId;
     this.signal = signal;
     this.langfuse = langfuse;
     this.subagentUsageSink = subagentUsageSink;
+    this.subagentScope = subagentScope === true;
 
     if (agents.length === 0) {
       throw new Error('At least one agent configuration is required');
@@ -1272,7 +1276,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         eventDrivenMode: true,
         sessions: this.sessions,
         toolDefinitions: toolDefMap,
-        agentId: agentContext?.agentId,
+        // `agentId` is the subagent-scope marker — set ONLY for child-run
+        // graphs (hooks fire for child scopes too, via the inherited
+        // run_id); `executingAgentId` always identifies the owning agent.
+        agentId: this.subagentScope ? agentContext?.agentId : undefined,
         executingAgentId: agentContext?.agentId,
         toolCallStepIds: this.toolCallStepIds,
         toolRegistry: agentContext?.toolRegistry,
@@ -1339,9 +1346,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       trace: traceToolNode,
       runLangfuse: this.langfuse,
       agentLangfuse: agentContext?.langfuse,
-      // `agentId` is intentionally left unset on this path (it is the
-      // subagent-scope marker); `executingAgentId` always identifies the owning
-      // agent so hooks can attribute the batch even at the top level.
+      // `agentId` is the subagent-scope marker — set ONLY for child-run
+      // graphs; `executingAgentId` always identifies the owning agent so
+      // hooks can attribute the batch even at the top level.
+      agentId: this.subagentScope ? agentContext?.agentId : undefined,
       executingAgentId: agentContext?.agentId,
       toolCallStepIds: this.toolCallStepIds,
       errorHandler: (data, metadata): Promise<boolean> =>

package/src/hooks/HookRegistry.ts

@@ -13,6 +13,17 @@ import type { HookEvent, HookMatcher } from './types';
  */
 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.
+ */
+const RESULT_ALTERING_HOOK_EVENTS = [
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+] as const satisfies readonly HookEvent[];
+
 /**
  * Snapshot of a halt request raised by a hook returning
  * `preventContinuation: true`. The SDK's run loop polls for this between
@@ -196,6 +207,31 @@ export class HookRegistry {
     this.haltSignals.delete(sessionId);
   }
 
+  /**
+   * True when any registered hook can alter a tool result before or after
+   * execution (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`). Eager
+   * tool execution and early completion emission gate on this instead of
+   * registry presence, so observation-only registries (e.g. a
+   * `PostToolBatch` steering drain) keep those fast paths. With
+   * `sessionId`, checks global + that session; without it, conservatively
+   * scans every session bucket.
+   */
+  hasResultAlteringHooks(sessionId?: string): boolean {
+    if (hasResultAlteringInBucket(this.global)) {
+      return true;
+    }
+    if (sessionId !== undefined) {
+      const bucket = this.sessions.get(sessionId);
+      return bucket !== undefined && hasResultAlteringInBucket(bucket);
+    }
+    for (const bucket of this.sessions.values()) {
+      if (hasResultAlteringInBucket(bucket)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   /** True if at least one matcher exists for `event` (global + session). */
   hasHookFor(event: HookEvent, sessionId?: string): boolean {
     if (readList(this.global, event).length > 0) {
@@ -242,6 +278,15 @@ function readList(
   return bucket[event] ?? [];
 }
 
+function hasResultAlteringInBucket(bucket: MatcherBucket): boolean {
+  for (const event of RESULT_ALTERING_HOOK_EVENTS) {
+    if (readList(bucket, event).length > 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function removeFromList<E extends HookEvent>(
   list: HookMatcher<HookEvent>[],
   matcher: HookMatcher<E>

package/src/hooks/__tests__/HookRegistry.test.ts

@@ -187,4 +187,52 @@ describe('HookRegistry', () => {
       }
     });
   });
+
+  describe('hasResultAlteringHooks', () => {
+    it('returns false for an empty registry', () => {
+      const registry = new HookRegistry();
+      expect(registry.hasResultAlteringHooks()).toBe(false);
+      expect(registry.hasResultAlteringHooks('run-1')).toBe(false);
+    });
+
+    it('returns false when only observation hooks are registered', () => {
+      const registry = new HookRegistry();
+      registry.register('PostToolBatch', { hooks: [async () => ({})] });
+      registry.register('Stop', { hooks: [async () => ({})] });
+      expect(registry.hasResultAlteringHooks()).toBe(false);
+      expect(registry.hasResultAlteringHooks('run-1')).toBe(false);
+    });
+
+    it('returns true for each result-altering event registered globally', () => {
+      for (const event of [
+        'PreToolUse',
+        'PostToolUse',
+        'PostToolUseFailure',
+      ] as const) {
+        const registry = new HookRegistry();
+        registry.register(event, { hooks: [async () => ({})] });
+        expect(registry.hasResultAlteringHooks()).toBe(true);
+        expect(registry.hasResultAlteringHooks('any-session')).toBe(true);
+      }
+    });
+
+    it('scopes session lookups to the given sessionId', () => {
+      const registry = new HookRegistry();
+      registry.registerSession('run-a', 'PreToolUse', makePreToolUseMatcher());
+      expect(registry.hasResultAlteringHooks('run-a')).toBe(true);
+      expect(registry.hasResultAlteringHooks('run-b')).toBe(false);
+    });
+
+    it('conservatively scans all sessions when no sessionId is given', () => {
+      const registry = new HookRegistry();
+      registry.registerSession(
+        'run-a',
+        'PostToolUse',
+        makePostToolUseMatcher()
+      );
+      expect(registry.hasResultAlteringHooks()).toBe(true);
+      registry.clearSession('run-a');
+      expect(registry.hasResultAlteringHooks()).toBe(false);
+    });
+  });
 });