@illuma-ai/agents 1.5.1 → 2.1.1

package/src/agents/AgentContext.ts

@@ -12,8 +12,6 @@ import type * as t from '@/types';
 import type { createPruneMessages } from '@/messages';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { ContentTypes, Providers } from '@/common';
-import { MAX_SYSTEM_CACHE_BLOCKS } from '@/types/agent-cache';
-import { isBedrockCacheSupported } from '@/llm/bedrock/cacheSupport';
 import { toJsonSchema } from '@/utils/schema';
 
 /**
@@ -39,9 +37,7 @@ export class AgentContext {
       toolEnd,
       toolRegistry,
       toolDefinitions,
-      system_cache_blocks,
       instructions,
-      instructions_cache_ttl,
       additional_instructions,
       streamBuffer,
       maxContextTokens,
@@ -56,6 +52,8 @@ export class AgentContext {
       persistedSummary,
       summarizationConfig,
       fileManifest,
+      system_cache_blocks,
+      instructions_cache_ttl,
     } = agentConfig;
 
     // Normalize structured output: support both camelCase and snake_case inputs
@@ -89,9 +87,7 @@ export class AgentContext {
       toolMap,
       toolRegistry,
       toolDefinitions,
-      systemCacheBlocks: system_cache_blocks,
       instructions,
-      instructionsCacheTtl: instructions_cache_ttl,
       additionalInstructions: additional_instructions,
       reasoningKey,
       toolEnd,
@@ -105,10 +101,12 @@ export class AgentContext {
       persistedSummary,
       summarizationConfig,
       fileManifest,
+      systemCacheBlocks: system_cache_blocks,
+      instructionsCacheTtl: instructions_cache_ttl,
     });
 
     /**
-     * Track subagent inputs on the context. `_sourceInputs`
+     * Track upstream-aligned subagent inputs on the context. `_sourceInputs`
      * preserves the original AgentInputs so SubagentExecutor can self-spawn
      * (`SubagentConfig.self === true`) without separate config; the other
      * two flow straight from agentConfig.
@@ -189,18 +187,9 @@ export class AgentContext {
   toolDefinitions?: t.LCTool[];
   /** Set of tool names discovered via tool search (to be loaded) */
   discoveredToolNames: Set<string> = new Set();
-  /**
-   * Cacheable system content blocks emitted before `instructions`. Each
-   * gets its own cache marker (cachePoint on Bedrock, cache_control on
-   * Anthropic). Earlier entries = wider cache key (best for cross-tenant
-   * sharing). See `src/types/agent-cache.ts`.
-   */
-  systemCacheBlocks?: t.SystemCacheBlock[];
-  /** Stable/cacheable instructions for this agent (gets trailing marker). */
+  /** Instructions for this agent */
   instructions?: string;
-  /** TTL for the trailing instructions cache marker. Defaults to '5m'. */
-  instructionsCacheTtl?: t.AgentCacheTTL;
-  /** Dynamic system tail (per-user / per-message — never cached). */
+  /** Additional instructions for this agent */
   additionalInstructions?: string;
   /**
    * Dynamic context that changes per-request (e.g., current time, user info).
@@ -279,6 +268,15 @@ export class AgentContext {
   summarizationConfig?: t.SummarizationConfig;
   /** Lightweight file manifest for file-aware compaction (IDs and names only, no content) */
   fileManifest?: t.FileManifestEntry[];
+  /**
+   * Workspace-shared system-message tiers. When set, each entry becomes a
+   * separate text block in the SystemMessage with its own cachePoint /
+   * cache_control marker, BEFORE the per-agent `instructions` block.
+   * See {@link t.AgentInputs.system_cache_blocks} for full semantics.
+   */
+  systemCacheBlocks?: Array<{ text: string; ttl?: '5m' | '1h' }>;
+  /** TTL hint for the per-agent instructions cache marker. Defaults to '5m'. */
+  instructionsCacheTtl?: '5m' | '1h';
   /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
   _sourceInputs?: t.AgentInputs;
   /** Subagent configurations for hierarchical delegation. */
@@ -299,9 +297,7 @@ export class AgentContext {
     toolMap,
     toolRegistry,
     toolDefinitions,
-    systemCacheBlocks,
     instructions,
-    instructionsCacheTtl,
     additionalInstructions,
     dynamicContext,
     reasoningKey,
@@ -314,6 +310,8 @@ export class AgentContext {
     persistedSummary,
     summarizationConfig,
     fileManifest,
+    systemCacheBlocks,
+    instructionsCacheTtl,
   }: {
     agentId: string;
     name?: string;
@@ -327,9 +325,7 @@ export class AgentContext {
     toolMap?: t.ToolMap;
     toolRegistry?: t.LCToolRegistry;
     toolDefinitions?: t.LCTool[];
-    systemCacheBlocks?: t.SystemCacheBlock[];
     instructions?: string;
-    instructionsCacheTtl?: t.AgentCacheTTL;
     additionalInstructions?: string;
     dynamicContext?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
@@ -344,6 +340,8 @@ export class AgentContext {
     persistedSummary?: string;
     summarizationConfig?: t.SummarizationConfig;
     fileManifest?: t.FileManifestEntry[];
+    systemCacheBlocks?: Array<{ text: string; ttl?: '5m' | '1h' }>;
+    instructionsCacheTtl?: '5m' | '1h';
   }) {
     this.agentId = agentId;
     this.name = name;
@@ -357,20 +355,7 @@ export class AgentContext {
     this.toolMap = toolMap;
     this.toolRegistry = toolRegistry;
     this.toolDefinitions = toolDefinitions;
-    if (
-      systemCacheBlocks &&
-      systemCacheBlocks.length > MAX_SYSTEM_CACHE_BLOCKS
-    ) {
-      throw new Error(
-        `system_cache_blocks supports at most ${MAX_SYSTEM_CACHE_BLOCKS} entries ` +
-          `(received ${systemCacheBlocks.length}); excess entries would exceed ` +
-          `Bedrock's 4-cachePoint per-request budget once the tools array and ` +
-          `trailing 'instructions' marker are counted. See src/types/agent-cache.ts.`,
-      );
-    }
-    this.systemCacheBlocks = systemCacheBlocks;
     this.instructions = instructions;
-    this.instructionsCacheTtl = instructionsCacheTtl;
     this.additionalInstructions = additionalInstructions;
     this.dynamicContext = dynamicContext;
     this.structuredOutput = structuredOutput;
@@ -378,6 +363,12 @@ export class AgentContext {
     this.persistedSummary = persistedSummary;
     this.summarizationConfig = summarizationConfig;
     this.fileManifest = fileManifest;
+    if (systemCacheBlocks && systemCacheBlocks.length > 0) {
+      this.systemCacheBlocks = systemCacheBlocks;
+    }
+    if (instructionsCacheTtl) {
+      this.instructionsCacheTtl = instructionsCacheTtl;
+    }
     if (reasoningKey) {
       this.reasoningKey = reasoningKey;
     }
@@ -605,11 +596,8 @@ export class AgentContext {
     }
 
     // Stale or first access - rebuild
-    this.cachedSystemRunnable = this.buildSystemRunnable({
-      systemCacheBlocks: this.systemCacheBlocks ?? [],
-      stableInstructions: this.buildStableInstructionsString(),
-      dynamicInstructions: this.buildDynamicInstructionsString(),
-    });
+    const instructionsString = this.buildInstructionsString();
+    this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
     this.systemRunnableStale = false;
     return this.cachedSystemRunnable;
   }
@@ -620,27 +608,17 @@ export class AgentContext {
    */
   initializeSystemRunnable(): void {
     if (this.systemRunnableStale || this.cachedSystemRunnable === undefined) {
-      this.cachedSystemRunnable = this.buildSystemRunnable({
-        systemCacheBlocks: this.systemCacheBlocks ?? [],
-        stableInstructions: this.buildStableInstructionsString(),
-        dynamicInstructions: this.buildDynamicInstructionsString(),
-      });
+      const instructionsString = this.buildInstructionsString();
+      this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
       this.systemRunnableStale = false;
     }
   }
 
   /**
-   * Builds the cacheable instructions string (without creating SystemMessage).
-   * Includes agent identity preamble, the agent's static instructions, and
-   * programmatic-only tool documentation. This is the part of the system
-   * message that stays byte-stable across turns and across users for the
-   * same agent — the prompt cache prefix.
-   *
-   * Per-user/per-message dynamic context belongs in
-   * `buildDynamicInstructionsString()` so it does not invalidate the cache
-   * marker. (See `feedback_cache_stability_invariant` for the rule.)
+   * Builds the raw instructions string (without creating SystemMessage).
+   * Includes agent identity preamble and handoff context when available.
    */
-  private buildStableInstructionsString(): string {
+  private buildInstructionsString(): string {
     const parts: string[] = [];
 
     /** Build agent identity and handoff context preamble */
@@ -654,27 +632,7 @@ export class AgentContext {
       parts.push(this.instructions);
     }
 
-    /** Add programmatic tools documentation */
-    const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
-    if (programmaticToolsDoc) {
-      parts.push(programmaticToolsDoc);
-    }
-
-    return parts.join('\n\n');
-  }
-
-  /**
-   * Builds the dynamic system-tail string (without creating SystemMessage).
-   * Keep this out of prompt-cache-marked content so volatile per-call
-   * context does not invalidate the stable prefix.
-   *
-   * `additional_instructions` is treated as dynamic (per-user/per-message
-   * memory, runtime context, etc.) and intentionally excluded from the
-   * cacheable prefix.
-   */
-  private buildDynamicInstructionsString(): string {
-    const parts: string[] = [];
-
+    /** Add additional instructions */
     if (
       this.additionalInstructions != null &&
       this.additionalInstructions !== ''
@@ -682,6 +640,12 @@ export class AgentContext {
       parts.push(this.additionalInstructions);
     }
 
+    /** Add programmatic tools documentation */
+    const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
+    if (programmaticToolsDoc) {
+      parts.push(programmaticToolsDoc);
+    }
+
     return parts.join('\n\n');
   }
 
@@ -737,168 +701,121 @@ export class AgentContext {
   }
 
   /**
-   * True when Anthropic prompt caching is enabled for this agent.
-   * Used by `buildSystemRunnable` to decide whether to emit a cache_control
-   * marker on the stable instructions prefix.
-   */
-  private hasAnthropicPromptCache(): boolean {
-    if (this.provider !== Providers.ANTHROPIC) {
-      return false;
-    }
-    const anthropicOptions = this.clientOptions as
-      | t.AnthropicClientOptions
-      | undefined;
-    return anthropicOptions?.promptCache === true;
-  }
-
-  /**
-   * True when Bedrock prompt caching is enabled for this agent AND the
-   * configured model supports `cachePoint` blocks. Only Claude (and Nova)
-   * models on Bedrock honour cachePoint — Llama / Titan reject it.
-   *
-   * Used by `buildSystemRunnable` to inline a `cachePoint` block right
-   * after the stable system text so the system prefix is cached at the
-   * AWS account level (cross-user, cross-conversation).
+   * Build system runnable from pre-built instructions string.
+   * Only called when content has actually changed.
    */
-  private hasBedrockPromptCache(): boolean {
-    if (this.provider !== Providers.BEDROCK) {
-      return false;
-    }
-    const bedrockOptions = this.clientOptions as
-      | (t.BedrockAnthropicClientOptions & {
-          model?: string;
-          bedrockCacheModelPatterns?: readonly RegExp[];
-        })
-      | undefined;
-    if (bedrockOptions?.promptCache !== true) {
-      return false;
-    }
-    /* Allowlist-based check (see src/llm/bedrock/cacheSupport.ts). The
-     * `bedrockCacheModelPatterns` clientOption lets consumers add new
-     * model patterns without forking the library — useful when AWS adds
-     * a new family before the next library release. */
-    return isBedrockCacheSupported(
-      bedrockOptions.model,
-      bedrockOptions.bedrockCacheModelPatterns,
-    );
-  }
-
-  /**
-   * Build system runnable from cacheable blocks + the trailing
-   * `instructions` block + optional dynamic tail.
-   *
-   *   ┌──────────────────────────────────────────┐
-   *   │ system_cache_blocks[0].text              │ ← consumer-defined block 0
-   *   ├──── cache marker (TTL = blocks[0].ttl) ──┤
-   *   │ system_cache_blocks[1].text              │ ← consumer-defined block 1
-   *   ├──── cache marker (TTL = blocks[1].ttl) ──┤
-   *   │ instructions                             │ ← per-agent stable
-   *   ├──── cache marker (TTL = instructionsCacheTtl) ┤
-   *   │ additional_instructions                  │ ← dynamic (uncached)
-   *   └──────────────────────────────────────────┘
-   *
-   * If `system_cache_blocks` is empty, behavior reduces to the 2-tier
-   * (instructions + dynamic) path used by simpler consumers.
-   *
-   * Provider-specific cache marker:
-   *   - Anthropic: `cache_control: { type: 'ephemeral', ttl?: '1h'|'5m' }` on
-   *     each cacheable text block. Up to 4 cache breakpoints per workspace.
-   *   - Bedrock (Claude/Nova): a `{ cachePoint: { type: 'default', ttl?: '1h'|'5m' } }`
-   *     block inserted after each cacheable section. Up to 4 cachePoints per
-   *     request, of which the tools array can consume up to 2.
-   *
-   * Cache key composition: every byte from message start to a given cache
-   * marker forms that marker's cache key. Earlier blocks = wider cache key
-   * = more cross-tenant share. Place the most stable content first.
-   */
-  private buildSystemRunnable({
-    systemCacheBlocks,
-    stableInstructions,
-    dynamicInstructions,
-  }: {
-    systemCacheBlocks: t.SystemCacheBlock[];
-    stableInstructions: string;
-    dynamicInstructions: string;
-  }):
+  private buildSystemRunnable(
+    instructionsString: string
+  ):
     | Runnable<
         BaseMessage[],
         (BaseMessage | SystemMessage)[],
         RunnableConfig<Record<string, unknown>>
       >
     | undefined {
-    const hasAnyCacheBlocks = systemCacheBlocks.length > 0;
-    if (!hasAnyCacheBlocks && !stableInstructions && !dynamicInstructions) {
+    if (!instructionsString) {
       // Remove previous tokens if we had a system message before
       this.instructionTokens -= this.systemMessageTokens;
       this.systemMessageTokens = 0;
       return undefined;
     }
 
-    const useAnthropicCache = this.hasAnthropicPromptCache();
-    const useBedrockCache = this.hasBedrockPromptCache();
-    const instructionsTtl: t.AgentCacheTTL = this.instructionsCacheTtl ?? '5m';
+    let finalInstructions: string | BaseMessageFields = instructionsString;
 
-    let finalInstructions: string | BaseMessageFields;
-    if (useAnthropicCache) {
-      type AnthropicTextBlock = {
-        type: 'text';
-        text: string;
-        cache_control?: { type: 'ephemeral'; ttl?: t.AgentCacheTTL };
-      };
-      const content: AnthropicTextBlock[] = [];
-      // Emit each system_cache_blocks entry with its own cache_control.
-      for (const block of systemCacheBlocks) {
-        if (!block.text) continue;
-        content.push({
-          type: 'text',
-          text: block.text,
-          cache_control: { type: 'ephemeral', ttl: block.ttl ?? '5m' },
-        });
-      }
-      // Trailing stable instructions block (also cacheable).
-      if (stableInstructions) {
-        content.push({
-          type: 'text',
-          text: stableInstructions,
-          cache_control: { type: 'ephemeral', ttl: instructionsTtl },
-        });
-      }
-      if (dynamicInstructions) {
-        // Dynamic tail: NO cache_control so it doesn't shift the cache prefix.
-        content.push({ type: 'text', text: dynamicInstructions });
-      }
-      finalInstructions = { content } as BaseMessageFields;
-    } else if (useBedrockCache && (hasAnyCacheBlocks || stableInstructions)) {
-      type BedrockBlock =
-        | { type: 'text'; text: string }
-        | { cachePoint: { type: 'default'; ttl?: t.AgentCacheTTL } };
-      const content: BedrockBlock[] = [];
-      // Emit each system_cache_blocks entry as text + cachePoint pair.
-      for (const block of systemCacheBlocks) {
-        if (!block.text) continue;
-        content.push({ type: 'text', text: block.text });
-        content.push({
-          cachePoint: { type: 'default', ttl: block.ttl ?? '5m' },
-        });
-      }
-      if (stableInstructions) {
-        content.push({ type: 'text', text: stableInstructions });
-        content.push({
-          cachePoint: { type: 'default', ttl: instructionsTtl },
-        });
-      }
-      if (dynamicInstructions) {
-        content.push({ type: 'text', text: dynamicInstructions });
+    /**
+     * Tiered system-message assembly. When `systemCacheBlocks` is set, build
+     * a multi-block SystemMessage so each tier has its own cache breakpoint:
+     *
+     *   [tier1_block_1][tier1_cachePoint]...[tier1_block_N][tier1_cachePoint]
+     *   [instructions][instructions_cachePoint]
+     *
+     * Forward-prefix-hash means agents in the same workspace whose tier-1
+     * bytes are identical share the platform cache entry; only the per-agent
+     * `instructions` block invalidates per-agent.
+     *
+     * - Bedrock: emit `cachePoint: { type: 'default' }` blocks (handled by
+     *   `convertSystemMessageToConverseMessage`).
+     * - Anthropic: emit `cache_control: { type: 'ephemeral' }` on each text
+     *   block. (TTL hints are dropped for Anthropic — the SDK currently
+     *   only supports `'ephemeral'`. Bedrock cachePoint has no TTL knob.)
+     */
+    const hasTieredCache =
+      Array.isArray(this.systemCacheBlocks) &&
+      this.systemCacheBlocks.length > 0;
+    const isBedrock = this.provider === Providers.BEDROCK;
+    const isAnthropic = this.provider === Providers.ANTHROPIC;
+    const anthropicCacheEnabled =
+      isAnthropic &&
+      (this.clientOptions as t.AnthropicClientOptions | undefined)
+        ?.promptCache === true;
+    /**
+     * Bedrock cachePoint is Claude-only — Nova/Llama/Titan reject it.
+     * Mirrors the model check in `IllumaBedrockConverse.invocationParams`
+     * (src/llm/bedrock/index.ts:186-189).
+     */
+    const bedrockCacheEnabled =
+      isBedrock &&
+      (() => {
+        const opts = this.clientOptions as
+          | (t.BedrockAnthropicClientOptions & { model?: string })
+          | undefined;
+        const modelId = (opts?.model ?? '').toLowerCase();
+        const isClaudeModel =
+          modelId.includes('claude') || modelId.includes('anthropic');
+        return opts?.promptCache === true && isClaudeModel;
+      })();
+
+    if (hasTieredCache && (bedrockCacheEnabled || anthropicCacheEnabled)) {
+      /**
+       * Anthropic / Bedrock cap cache breakpoints at 4 per request. The
+       * lib already emits one for tools and up to two for messages, so we
+       * have at most 1 left for the system block. We spend it on Tier 1
+       * (the workspace-shared bytes) — per-agent Tier 2 caching is still
+       * achieved implicitly via the tools breakpoint that follows, since
+       * cache lookups are forward-prefix-hash.
+       *
+       * Tier 1 may itself be emitted as multiple text blocks (one per
+       * `systemCacheBlocks` entry); only the LAST gets the cache marker,
+       * the rest are plain text inside the same cached prefix.
+       */
+      const contentBlocks: Array<Record<string, unknown>> = [];
+      const tier1Blocks = this.systemCacheBlocks!.filter((b) => b?.text);
+      tier1Blocks.forEach((block, idx) => {
+        const isLast = idx === tier1Blocks.length - 1;
+        if (bedrockCacheEnabled) {
+          contentBlocks.push({ type: 'text', text: block.text });
+          if (isLast) {
+            contentBlocks.push({ cachePoint: { type: 'default' } });
+          }
+        } else if (isLast) {
+          contentBlocks.push({
+            type: 'text',
+            text: block.text,
+            cache_control: { type: 'ephemeral' },
+          });
+        } else {
+          contentBlocks.push({ type: 'text', text: block.text });
+        }
+      });
+      if (instructionsString) {
+        // No cache marker on the trailing per-agent block — tools'
+        // breakpoint covers it.
+        contentBlocks.push({ type: 'text', text: instructionsString });
       }
-      finalInstructions = { content } as unknown as BaseMessageFields;
-    } else {
-      finalInstructions = [
-        ...systemCacheBlocks.map((b) => b.text),
-        stableInstructions,
-        dynamicInstructions,
-      ]
-        .filter((part) => part !== '')
-        .join('\n\n');
+      finalInstructions = {
+        content: contentBlocks as unknown as BaseMessageFields['content'],
+      };
+    } else if (anthropicCacheEnabled) {
+      // Legacy single-block Anthropic caching (preserved for back-compat).
+      finalInstructions = {
+        content: [
+          {
+            type: 'text',
+            text: instructionsString,
+            cache_control: { type: 'ephemeral' },
+          },
+        ],
+      };
     }
 
     const systemMessage = new SystemMessage(finalInstructions);
@@ -974,49 +891,6 @@ export class AgentContext {
     }
   }
 
-  /** Active tool definitions for token accounting (excludes deferred-and-undiscovered entries
-   * and definitions whose `allowed_callers` exclude `'direct'`). Mirrors the gate
-   * `getEventDrivenToolsForBinding` applies so accounting and binding stay aligned. */
-  private getActiveToolDefinitions(): t.LCTool[] {
-    if (!this.toolDefinitions) {
-      return [];
-    }
-    return this.toolDefinitions.filter((def) => {
-      const allowedCallers = def.allowed_callers ?? ['direct'];
-      if (!allowedCallers.includes('direct')) {
-        return false;
-      }
-      return (
-        def.defer_loading !== true || this.discoveredToolNames.has(def.name)
-      );
-    });
-  }
-
-  /**
-   * Single source of truth for "which entries of `this.tools` should be
-   * treated as actually bound". Callers:
-   *   - `getToolsForBinding` (non-event-driven branch)
-   *   - `getEventDrivenToolsForBinding` (appends instance tools alongside
-   *     schema-only definitions)
-   *   - `calculateInstructionTokens` (counts schema bytes for accounting)
-   *
-   * In event-driven mode (`toolDefinitions` present) instance tools are
-   * appended unfiltered; outside event-driven mode they pass through
-   * `filterToolsForBinding`. Centralizing the decision here prevents the
-   * accounting/binding paths from drifting apart, which was the root
-   * cause of the original miscount (Fixes #121).
-   */
-  private getEffectiveInstanceTools(): t.GraphTools | undefined {
-    if (!this.tools) {
-      return undefined;
-    }
-    const isEventDriven = (this.toolDefinitions?.length ?? 0) > 0;
-    if (isEventDriven || !this.toolRegistry) {
-      return this.tools;
-    }
-    return this.filterToolsForBinding(this.tools);
-  }
-
   /**
    * Calculate tool tokens and add to instruction tokens
    * Note: System message tokens are calculated during systemRunnable creation
@@ -1034,17 +908,9 @@ export class AgentContext {
     // Reset per-tool breakdown
     this.toolsDetail = [];
 
-    /* Use `getEffectiveInstanceTools()` so accounting reflects exactly the
-     * subset that `getToolsForBinding` would emit — preventing the
-     * worst-case-ceiling miscount that triggered spurious `empty_messages`
-     * preflight rejections at low `maxContextTokens`. Deferred and
-     * non-`'direct'` `toolDefinitions` are excluded by
-     * `getActiveToolDefinitions()` below. */
-    const effectiveInstanceTools = this.getEffectiveInstanceTools();
-
     // Count tokens for bound tools (StructuredTool instances with .schema)
-    if (effectiveInstanceTools && effectiveInstanceTools.length > 0) {
-      for (const tool of effectiveInstanceTools) {
+    if (this.tools && this.tools.length > 0) {
+      for (const tool of this.tools) {
         const genericTool = tool as Record<string, unknown>;
         if (
           genericTool.schema != null &&
@@ -1073,27 +939,25 @@ export class AgentContext {
     // Count tokens for tool definitions (MCP / event-driven tools).
     // These are sent to the provider API as tool schemas alongside bound tools.
     // Both can be populated simultaneously (graph tools + MCP tools).
-    // Use `getActiveToolDefinitions()` so programmatic-only definitions
-    // (e.g. `allowed_callers: ['code_execution']`) and deferred-and-
-    // -undiscovered ones don't inflate `toolSchemaTokens` while never
-    // being bound to the model.
-    for (const def of this.getActiveToolDefinitions()) {
-      if (countedToolNames.has(def.name)) {
-        continue; // Already counted via this.tools
+    if (this.toolDefinitions && this.toolDefinitions.length > 0) {
+      for (const def of this.toolDefinitions) {
+        if (countedToolNames.has(def.name)) {
+          continue; // Already counted via this.tools
+        }
+        const schema = {
+          name: def.name,
+          description: def.description ?? '',
+          parameters: def.parameters ?? {},
+        };
+        const defTokens = tokenCounter(
+          new SystemMessage(JSON.stringify(schema))
+        );
+        this.toolsDetail.push({
+          name: def.name || 'unknown',
+          tokens: defTokens,
+        });
+        toolTokens += defTokens;
       }
-      const schema = {
-        name: def.name,
-        description: def.description ?? '',
-        parameters: def.parameters ?? {},
-      };
-      const defTokens = tokenCounter(
-        new SystemMessage(JSON.stringify(schema))
-      );
-      this.toolsDetail.push({
-        name: def.name || 'unknown',
-        tokens: defTokens,
-      });
-      toolTokens += defTokens;
     }
 
     // Store total tool tokens for breakdown reporting
@@ -1264,7 +1128,10 @@ export class AgentContext {
     }
 
     /** Traditional mode: filter actual tool instances */
-    const filtered = this.getEffectiveInstanceTools();
+    const filtered =
+      !this.tools || !this.toolRegistry
+        ? this.tools
+        : this.filterToolsForBinding(this.tools);
 
     if (this.graphTools && this.graphTools.length > 0) {
       return [...(filtered ?? []), ...this.graphTools];
@@ -1279,11 +1146,21 @@ export class AgentContext {
       return this.graphTools ?? [];
     }
 
-    /* Reuse `getActiveToolDefinitions()` so the binding gate matches the
-     * accounting filter exactly (single source of truth). */
-    const schemaTools = createSchemaOnlyTools(
-      this.getActiveToolDefinitions()
-    ) as t.GraphTools;
+    const defsToInclude = this.toolDefinitions.filter((def) => {
+      const allowedCallers = def.allowed_callers ?? ['direct'];
+      if (!allowedCallers.includes('direct')) {
+        return false;
+      }
+      if (
+        def.defer_loading === true &&
+        !this.discoveredToolNames.has(def.name)
+      ) {
+        return false;
+      }
+      return true;
+    });
+
+    const schemaTools = createSchemaOnlyTools(defsToInclude) as t.GraphTools;
 
     const allTools = [...schemaTools];
 
@@ -1291,9 +1168,6 @@ export class AgentContext {
       allTools.push(...this.graphTools);
     }
 
-    /* In event-driven mode, instance tools are appended UNFILTERED (matching
-     * `getEffectiveInstanceTools()`'s event-driven branch). Deferred /
-     * non-direct logic is represented in `toolDefinitions`, not here. */
     if (this.tools && this.tools.length > 0) {
       allTools.push(...this.tools);
     }