@librechat/agents 3.1.66-dev.0 → 3.1.67-dev.0

package/dist/types/agents/AgentContext.d.ts

@@ -86,6 +86,12 @@ export declare class AgentContext {
     toolDefinitions?: t.LCTool[];
     /** Set of tool names discovered via tool search (to be loaded) */
     discoveredToolNames: Set<string>;
+    /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
+    _sourceInputs?: t.AgentInputs;
+    /** Subagent configurations for hierarchical delegation. */
+    subagentConfigs?: t.SubagentConfig[];
+    /** Maximum subagent nesting depth. */
+    maxSubagentDepth?: number;
     /** Instructions for this agent */
     instructions?: string;
     /** Additional instructions for this agent */
@@ -230,6 +236,8 @@ export declare class AgentContext {
      * token counts.
      */
     updateTokenMapWithInstructions(baseTokenMap: Record<string, number>): void;
+    /** Active tool definitions for token accounting (excludes deferred-and-undiscovered entries). */
+    private getActiveToolDefinitions;
     /**
      * Calculate tool tokens and add to instruction tokens
      * Note: System message tokens are calculated during systemRunnable creation
@@ -284,6 +292,10 @@ export declare class AgentContext {
     /**
      * Returns a structured breakdown of how the context token budget is consumed.
      * Useful for diagnostics when context overflow or pruning issues occur.
+     *
+     * Note: `toolCount` reflects discoveries immediately, but `toolSchemaTokens`
+     * is a snapshot taken during `calculateInstructionTokens` and is not
+     * recomputed when `markToolsAsDiscovered` is called mid-run.
      */
     getTokenBudgetBreakdown(messages?: BaseMessage[]): t.TokenBudgetBreakdown;
     /**

package/dist/types/common/enum.d.ts

@@ -140,7 +140,8 @@ export declare enum Constants {
     SKILL_TOOL = "skill",
     READ_FILE = "read_file",
     BASH_TOOL = "bash_tool",
-    BASH_PROGRAMMATIC_TOOL_CALLING = "run_tools_with_bash"
+    BASH_PROGRAMMATIC_TOOL_CALLING = "run_tools_with_bash",
+    SUBAGENT = "subagent"
 }
 /** Tool names that use the code execution environment (shared session, file tracking). */
 export declare const CODE_EXECUTION_TOOLS: ReadonlySet<string>;

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

@@ -109,11 +109,22 @@ export interface StopFailureHookInput extends BaseHookInput {
 export interface PreCompactHookInput extends BaseHookInput {
     hook_event_name: 'PreCompact';
     messagesBeforeCount: number;
-    trigger: 'threshold' | 'manual' | 'error';
+    /**
+     * What triggered compaction. Matches `SummarizationTrigger.type` from the
+     * agent's summarization config. `'default'` means no trigger was
+     * configured and compaction fired because messages were pruned.
+     */
+    trigger: 'token_ratio' | 'remaining_tokens' | 'messages_to_refine' | 'default' | (string & {});
 }
 export interface PostCompactHookInput extends BaseHookInput {
     hook_event_name: 'PostCompact';
     summary: string;
+    /**
+     * Number of messages remaining after compaction. The summarize node
+     * returns a `removeAll` signal that clears all messages from state;
+     * the summary itself is injected into the system prompt, not as a
+     * message. This is `0` at the point of hook dispatch.
+     */
     messagesAfterCount: number;
 }
 /** Discriminated union of every hook input shape. */

package/dist/types/index.d.ts

@@ -11,6 +11,8 @@ export * from './tools/BashExecutor';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/BashProgrammaticToolCalling';
 export * from './tools/SkillTool';
+export * from './tools/SubagentTool';
+export * from './tools/subagent';
 export * from './tools/ReadFile';
 export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';

package/dist/types/summarization/node.d.ts

@@ -1,6 +1,7 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { AgentContext } from '@/agents/AgentContext';
+import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
 /** Structured checkpoint prompt for fresh summarization (no prior summary). */
 export declare const DEFAULT_SUMMARIZATION_PROMPT = "Hold on, before you continue I need you to write me a checkpoint of everything so far. Your context window is filling up and this checkpoint replaces the messages above, so capture everything you need to pick right back up.\n\nDon't second-guess or fact-check anything you did, your tool results reflect exactly what happened. If a tool result appears truncated, that's just a display artifact from context management: the tool executed fully. Just record what you did and what you observed. Only the checkpoint, don't respond to me or continue the conversation.\n\n## Checkpoint\n\n## Goal\nWhat I asked you to do and any sub-goals you identified.\n\n## Constraints & Preferences\nAny rules, preferences, or configuration I established.\n\n## Progress\n### Done\n- What you completed and the outcomes\n\n### In Progress\n- What you're currently working on\n\n## Key Decisions\nDecisions you made and why.\n\n## Next Steps\nConcrete task actions remaining, in priority order.\n\n## Critical Context\nExact identifiers, names, error messages, URLs, and details you need to preserve verbatim.\n\nRules:\n- Record what you did and observed, don't judge or re-evaluate it\n- For each tool call: the tool name, key inputs, and the outcome\n- Preserve exact identifiers, names, errors, and references verbatim\n- Short declarative sentences\n- Skip empty sections";
@@ -14,6 +15,7 @@ interface CreateSummarizeNodeParams {
         config?: RunnableConfig;
         runId?: string;
         isMultiAgent: boolean;
+        hookRegistry?: HookRegistry;
         dispatchRunStep: (runStep: t.RunStep, config?: RunnableConfig) => Promise<void>;
         dispatchRunStepCompleted: (stepId: string, result: t.StepCompleted, config?: RunnableConfig) => Promise<void>;
     };

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

@@ -0,0 +1,36 @@
+import { Constants } from '@/common';
+import type { SubagentConfig } from '@/types';
+import type { JsonSchemaType, LCTool } from '@/types/tools';
+export declare const SubagentToolName = Constants.SUBAGENT;
+export declare const SubagentToolDescription = "Delegate a task to a specialized subagent that runs in an isolated context window. The subagent executes independently and returns only its final text result \u2014 all intermediate tool calls, reasoning, and context stay isolated.\n\nWHEN TO USE:\n- The task is self-contained and can be described in a single prompt.\n- You want to offload verbose or exploratory work without bloating your own context.\n- A specialized subagent is available for the task domain.\n\nWHAT HAPPENS:\n- A fresh agent is created with the task description as its only input.\n- The subagent runs to completion using its own tools and context.\n- Only the final text response is returned to you.\n\nCONSTRAINTS:\n- subagent_type must match one of the available types listed below.\n- The subagent cannot see your conversation history.";
+export declare const SubagentToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly description: {
+            readonly type: "string";
+            readonly description: "Complete task description for the subagent. This is the ONLY information it receives — include all necessary context, requirements, and constraints.";
+        };
+        readonly subagent_type: {
+            readonly type: "string";
+            readonly description: "Which subagent type to delegate to. Must be one of the available types.";
+        };
+    };
+    readonly required: string[];
+};
+export declare const SubagentToolDefinition: LCTool;
+/**
+ * Build the name, schema, and description params for `tool()` from available configs.
+ * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
+ * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
+ */
+export declare function buildSubagentToolParams(configs: SubagentConfig[]): {
+    name: string;
+    schema: JsonSchemaType;
+    description: string;
+};
+/**
+ * Create a SubagentTool LCTool definition with dynamic enum and description
+ * populated from the available subagent configs.
+ * Used for the tool registry in event-driven mode.
+ */
+export declare function createSubagentToolDefinition(configs: SubagentConfig[]): LCTool;

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

@@ -0,0 +1,83 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { AgentInputs, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, TokenCounter } from '@/types';
+import type { HookRegistry } from '@/hooks';
+import type { AgentContext } from '@/agents/AgentContext';
+import type { StandardGraph } from '@/graphs/Graph';
+export type SubagentExecuteParams = {
+    description: string;
+    subagentType: string;
+    threadId?: string;
+};
+export type SubagentExecuteResult = {
+    content: string;
+    messages: BaseMessage[];
+};
+/**
+ * Factory that constructs a child graph for subagent execution. Injected
+ * rather than imported so that `SubagentExecutor` does not have a runtime
+ * dependency on `StandardGraph` — this avoids a circular dependency between
+ * `src/graphs/Graph.ts` and `src/tools/subagent/` that would otherwise break
+ * Rollup's chunking under `preserveModules`.
+ */
+export type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;
+export type SubagentExecutorOptions = {
+    configs: Map<string, ResolvedSubagentConfig>;
+    parentSignal?: AbortSignal;
+    hookRegistry?: HookRegistry;
+    parentRunId: string;
+    parentAgentId?: string;
+    tokenCounter?: TokenCounter;
+    /** Remaining nesting budget. 0 or negative blocks execution. */
+    maxDepth?: number;
+    /**
+     * Factory for constructing the isolated child graph. Callers pass
+     * `(input) => new StandardGraph(input)` — injected to break a circular
+     * module dependency.
+     */
+    createChildGraph: ChildGraphFactory;
+};
+export declare class SubagentExecutor {
+    private readonly configs;
+    private readonly parentSignal?;
+    private readonly hookRegistry?;
+    private readonly parentRunId;
+    private readonly parentAgentId?;
+    private readonly tokenCounter?;
+    private readonly maxDepth;
+    private readonly createChildGraph;
+    constructor(options: SubagentExecutorOptions);
+    execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;
+}
+/**
+ * Walk messages from last to first, returning the text content of the most
+ * recent AIMessage that has any. Non-text blocks (tool_use, thinking,
+ * redacted_thinking, tool_result) are stripped. If the last AIMessage is
+ * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
+ * continues to earlier AIMessages so partial progress is salvaged — this
+ * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
+ * Returns "Task completed" only when no AIMessage in the history contains
+ * any text.
+ */
+export declare function filterSubagentResult(messages: BaseMessage[]): string;
+/**
+ * Resolve self-spawn configs by filling in agentInputs from the parent context.
+ * Returns configs with agentInputs guaranteed present. Throws on duplicate
+ * `type` values to prevent silent config shadowing.
+ */
+export declare function resolveSubagentConfigs(configs: SubagentConfig[], parentContext: AgentContext): ResolvedSubagentConfig[];
+/**
+ * Build child AgentInputs from a resolved config, stripping nesting and
+ * event-driven fields. When `allowNested: true`, the child's
+ * `maxSubagentDepth` is decremented so that depth is consumed as the call
+ * chain deepens across graph boundaries — the parent's executor-level check
+ * alone cannot see into the child graph's separate executor.
+ *
+ * @remarks Advanced utility: exported primarily for testing and by
+ * {@link SubagentExecutor}. Host applications configuring subagents should
+ * not need to call this directly — it is invoked internally when a subagent
+ * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,
+ * child's decremented `maxSubagentDepth` on the returned inputs) is the
+ * mechanism that bounds nesting across graph boundaries; callers must
+ * respect it.
+ */
+export declare function buildChildInputs(config: ResolvedSubagentConfig, childAgentId: string, parentMaxDepth: number): AgentInputs;

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

@@ -0,0 +1,2 @@
+export { SubagentExecutor, filterSubagentResult, resolveSubagentConfigs, buildChildInputs, } from './SubagentExecutor';
+export type { SubagentExecuteParams, SubagentExecuteResult, SubagentExecutorOptions, ChildGraphFactory, } from './SubagentExecutor';

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

@@ -248,6 +248,27 @@ export type GraphEdge = {
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];
 };
+/** Configuration for a subagent type that can be spawned by a parent agent. */
+export type SubagentConfig = {
+    /** Identifier used in the tool's `subagent_type` enum (e.g. 'researcher', 'coder'). */
+    type: string;
+    /** Human-readable display name. */
+    name: string;
+    /** What this subagent specializes in — shown to the LLM. */
+    description: string;
+    /** Full agent config for the child graph. Omit when `self` is true. */
+    agentInputs?: AgentInputs;
+    /** When true, reuse the parent's AgentInputs (context isolation without separate config). */
+    self?: boolean;
+    /** Max AGENT→TOOLS cycles before forced stop (default: 25). */
+    maxTurns?: number;
+    /** Allow this subagent to spawn its own subagents (default: false). */
+    allowNested?: boolean;
+};
+/** SubagentConfig with agentInputs guaranteed present (self-spawn resolved). */
+export type ResolvedSubagentConfig = SubagentConfig & {
+    agentInputs: AgentInputs;
+};
 export interface AgentInputs {
     agentId: string;
     /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -294,6 +315,10 @@ export interface AgentInputs {
     maxToolResultChars?: number;
     /** Pre-computed tool schema token count (from cache). Skips recalculation when provided. */
     toolSchemaTokens?: number;
+    /** Subagent configurations for hierarchical delegation. Each defines a child agent type. */
+    subagentConfigs?: SubagentConfig[];
+    /** Maximum subagent nesting depth. Default 1 means top-level agents can spawn subagents but subagents cannot nest further. */
+    maxSubagentDepth?: number;
 }
 export interface ContextPruningConfig {
     enabled?: boolean;

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

@@ -28,7 +28,18 @@ export type AzureClientOptions = Partial<OpenAIChatInput> & Partial<AzureOpenAII
 } & BaseChatModelParams & {
     configuration?: OAIClientOptions;
 };
-export type ThinkingConfig = AnthropicInput['thinking'];
+/**
+ * Controls whether Claude's reasoning content is returned in adaptive
+ * thinking responses. Added for Claude Opus 4.7, which omits thinking by
+ * default unless the caller opts in with `'summarized'`.
+ * @see https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7#thinking-content-omitted-by-default
+ */
+export type ThinkingDisplay = 'summarized' | 'omitted';
+export type ThinkingConfigAdaptive = {
+    type: 'adaptive';
+    display?: ThinkingDisplay;
+};
+export type ThinkingConfig = NonNullable<AnthropicInput['thinking']> | ThinkingConfigAdaptive;
 export type ChatOpenAIToolType = BindToolsInput | OpenAIClient.ChatCompletionTool;
 export type CommonToolType = StructuredTool | ChatOpenAIToolType;
 export type AnthropicReasoning = {
@@ -41,7 +52,8 @@ export type GoogleThinkingConfig = {
     thinkingLevel?: string;
 };
 export type OpenAIClientOptions = ChatOpenAIFields;
-export type AnthropicClientOptions = AnthropicInput & {
+export type AnthropicClientOptions = Omit<AnthropicInput, 'thinking'> & {
+    thinking?: ThinkingConfig;
     promptCache?: boolean;
 };
 export type MistralAIClientOptions = ChatMistralAIInput;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.66-dev.0",
+  "version": "3.1.67-dev.0",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -77,6 +77,7 @@
     "multi-agent-chain": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-chain.ts",
     "multi-agent-sequence": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-sequence.ts",
     "multi-agent-conditional": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-conditional.ts",
+    "multi-agent-subagent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-subagent.ts",
     "multi-agent-supervisor": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-supervisor.ts",
     "test-handoff-preamble": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-handoff-preamble.ts",
     "multi-agent-list-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-multi-agent-list-handoff.ts",

package/src/agents/AgentContext.ts

@@ -55,6 +55,8 @@ export class AgentContext {
       contextPruningConfig,
       maxToolResultChars,
       toolSchemaTokens,
+      subagentConfigs,
+      maxSubagentDepth,
     } = agentConfig;
 
     const agentContext = new AgentContext({
@@ -82,6 +84,10 @@ export class AgentContext {
       maxToolResultChars,
     });
 
+    agentContext._sourceInputs = agentConfig;
+    agentContext.subagentConfigs = subagentConfigs;
+    agentContext.maxSubagentDepth = maxSubagentDepth;
+
     if (initialSummary?.text != null && initialSummary.text !== '') {
       agentContext.setInitialSummary(
         initialSummary.text,
@@ -198,6 +204,12 @@ export class AgentContext {
   toolDefinitions?: t.LCTool[];
   /** Set of tool names discovered via tool search (to be loaded) */
   discoveredToolNames: Set<string> = new Set();
+  /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
+  _sourceInputs?: t.AgentInputs;
+  /** Subagent configurations for hierarchical delegation. */
+  subagentConfigs?: t.SubagentConfig[];
+  /** Maximum subagent nesting depth. */
+  maxSubagentDepth?: number;
   /** Instructions for this agent */
   instructions?: string;
   /** Additional instructions for this agent */
@@ -664,6 +676,17 @@ export class AgentContext {
     this.indexTokenCountMap = { ...baseTokenMap };
   }
 
+  /** Active tool definitions for token accounting (excludes deferred-and-undiscovered entries). */
+  private getActiveToolDefinitions(): t.LCTool[] {
+    if (!this.toolDefinitions) {
+      return [];
+    }
+    return this.toolDefinitions.filter(
+      (def) =>
+        def.defer_loading !== true || this.discoveredToolNames.has(def.name)
+    );
+  }
+
   /**
    * Calculate tool tokens and add to instruction tokens
    * Note: System message tokens are calculated during systemRunnable creation
@@ -674,8 +697,20 @@ export class AgentContext {
     let toolTokens = 0;
     const countedToolNames = new Set<string>();
 
-    if (this.tools && this.tools.length > 0) {
-      for (const tool of this.tools) {
+    /**
+     * Iterate both `tools` (user-provided instance tools) and `graphTools`
+     * (graph-managed tools like handoff + subagent). `graphTools` is often
+     * populated after `fromConfig()` kicks off the initial calculation, so
+     * callers that mutate `graphTools` must re-trigger this method to
+     * refresh `toolSchemaTokens`.
+     */
+    const instanceTools: t.GraphTools = [
+      ...((this.tools as t.GenericTool[] | undefined) ?? []),
+      ...((this.graphTools as t.GenericTool[] | undefined) ?? []),
+    ];
+
+    if (instanceTools.length > 0) {
+      for (const tool of instanceTools) {
         const genericTool = tool as Record<string, unknown>;
         if (
           genericTool.schema != null &&
@@ -697,21 +732,19 @@ export class AgentContext {
       }
     }
 
-    if (this.toolDefinitions && this.toolDefinitions.length > 0) {
-      for (const def of this.toolDefinitions) {
-        if (countedToolNames.has(def.name)) {
-          continue;
-        }
-        const schema = {
-          type: 'function',
-          function: {
-            name: def.name,
-            description: def.description ?? '',
-            parameters: def.parameters ?? {},
-          },
-        };
-        toolTokens += tokenCounter(new SystemMessage(JSON.stringify(schema)));
+    for (const def of this.getActiveToolDefinitions()) {
+      if (countedToolNames.has(def.name)) {
+        continue;
       }
+      const schema = {
+        type: 'function',
+        function: {
+          name: def.name,
+          description: def.description ?? '',
+          parameters: def.parameters ?? {},
+        },
+      };
+      toolTokens += tokenCounter(new SystemMessage(JSON.stringify(schema)));
     }
 
     const isAnthropic =
@@ -860,11 +893,15 @@ export class AgentContext {
   /**
    * Returns a structured breakdown of how the context token budget is consumed.
    * Useful for diagnostics when context overflow or pruning issues occur.
+   *
+   * Note: `toolCount` reflects discoveries immediately, but `toolSchemaTokens`
+   * is a snapshot taken during `calculateInstructionTokens` and is not
+   * recomputed when `markToolsAsDiscovered` is called mid-run.
    */
   getTokenBudgetBreakdown(messages?: BaseMessage[]): t.TokenBudgetBreakdown {
     const maxContextTokens = this.maxContextTokens ?? 0;
     const toolCount =
-      (this.tools?.length ?? 0) + (this.toolDefinitions?.length ?? 0);
+      (this.tools?.length ?? 0) + this.getActiveToolDefinitions().length;
     const messageCount = messages?.length ?? 0;
 
     let messageTokens = 0;

package/src/agents/__tests__/AgentContext.test.ts

@@ -375,6 +375,116 @@ describe('AgentContext', () => {
 
       expect(ctx.instructionTokens).toBeGreaterThan(initialTokens);
     });
+
+    it('excludes deferred-undiscovered toolDefinitions from toolSchemaTokens', async () => {
+      const activeDef: t.LCTool = {
+        name: 'active_tool',
+        description: 'Always loaded',
+        parameters: { type: 'object', properties: {} },
+      };
+      const deferredDef: t.LCTool = {
+        name: 'deferred_tool',
+        description: 'Loaded via tool search',
+        parameters: { type: 'object', properties: {} },
+        defer_loading: true,
+      };
+
+      const ctxBase = createBasicContext({
+        agentConfig: { toolDefinitions: [activeDef] },
+        tokenCounter: mockTokenCounter,
+      });
+      const ctxWithDeferred = createBasicContext({
+        agentConfig: { toolDefinitions: [activeDef, deferredDef] },
+        tokenCounter: mockTokenCounter,
+      });
+
+      await ctxBase.tokenCalculationPromise;
+      await ctxWithDeferred.tokenCalculationPromise;
+
+      expect(ctxWithDeferred.toolSchemaTokens).toBe(ctxBase.toolSchemaTokens);
+    });
+
+    it('includes deferred toolDefinitions once discovered via discoveredTools input', async () => {
+      const toolDefinitions: t.LCTool[] = [
+        {
+          name: 'deferred_tool',
+          description: 'Loaded via tool search',
+          parameters: { type: 'object', properties: {} },
+          defer_loading: true,
+        },
+      ];
+
+      const ctxUndiscovered = createBasicContext({
+        agentConfig: { toolDefinitions },
+        tokenCounter: mockTokenCounter,
+      });
+      const ctxDiscovered = createBasicContext({
+        agentConfig: { toolDefinitions, discoveredTools: ['deferred_tool'] },
+        tokenCounter: mockTokenCounter,
+      });
+
+      await ctxUndiscovered.tokenCalculationPromise;
+      await ctxDiscovered.tokenCalculationPromise;
+
+      expect(ctxUndiscovered.toolSchemaTokens).toBe(0);
+      expect(ctxDiscovered.toolSchemaTokens).toBeGreaterThan(0);
+    });
+
+    it('getTokenBudgetBreakdown toolCount excludes deferred-undiscovered toolDefinitions', () => {
+      const toolDefinitions: t.LCTool[] = [
+        {
+          name: 'active',
+          parameters: { type: 'object', properties: {} },
+        },
+        {
+          name: 'deferred',
+          defer_loading: true,
+          parameters: { type: 'object', properties: {} },
+        },
+      ];
+
+      const ctx = createBasicContext({ agentConfig: { toolDefinitions } });
+
+      expect(ctx.getTokenBudgetBreakdown().toolCount).toBe(1);
+    });
+
+    it('getTokenBudgetBreakdown toolCount reflects newly discovered deferred tools', () => {
+      const toolDefinitions: t.LCTool[] = [
+        {
+          name: 'deferred',
+          defer_loading: true,
+          parameters: { type: 'object', properties: {} },
+        },
+      ];
+
+      const ctx = createBasicContext({ agentConfig: { toolDefinitions } });
+
+      expect(ctx.getTokenBudgetBreakdown().toolCount).toBe(0);
+      ctx.markToolsAsDiscovered(['deferred']);
+      expect(ctx.getTokenBudgetBreakdown().toolCount).toBe(1);
+    });
+
+    it('toolSchemaTokens snapshot does not auto-update after markToolsAsDiscovered', async () => {
+      const toolDefinitions: t.LCTool[] = [
+        {
+          name: 'deferred',
+          description: 'Loaded via tool search',
+          parameters: { type: 'object', properties: {} },
+          defer_loading: true,
+        },
+      ];
+
+      const ctx = createBasicContext({
+        agentConfig: { toolDefinitions },
+        tokenCounter: mockTokenCounter,
+      });
+
+      await ctx.tokenCalculationPromise;
+      expect(ctx.toolSchemaTokens).toBe(0);
+
+      ctx.markToolsAsDiscovered(['deferred']);
+      expect(ctx.toolSchemaTokens).toBe(0);
+    });
   });
 
   describe('reset()', () => {

package/src/common/enum.ts

@@ -186,6 +186,7 @@ export enum Constants {
   READ_FILE = 'read_file',
   BASH_TOOL = 'bash_tool',
   BASH_PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_bash',
+  SUBAGENT = 'subagent',
 }
 
 /** Tool names that use the code execution environment (shared session, file tracking). */