@genesislcap/ai-assistant 14.466.0 → 14.467.0-GNEC-1369.1

package/dist/ai-assistant.api.json

@@ -5475,7 +5475,7 @@
                 },
                 {
                   "kind": "Content",
-                  "text": "<string, unknown>;\n            kind: \"event\";\n        })[];\n        meta: {\n            timestamp: string;\n            host: string;\n            agentSummary: ({\n                toolDefinitions: string | import(\"@genesislcap/foundation-ai\")."
+                  "text": "<string, unknown>;\n            kind: \"event\";\n        })[];\n        meta: {\n            timestamp: string;\n            host: string;\n            agentSummary: {\n                toolDefinitions: string | import(\"@genesislcap/foundation-ai\")."
                 },
                 {
                   "kind": "Reference",
@@ -5484,16 +5484,25 @@
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n                toolHandlers: any;\n                onActivate: any;\n                onDeactivate: any;\n                getDebugSnapshot: any;\n                description: string;\n                fallback?: never;\n                excludeFromClassifier?: boolean;\n                name: string;\n                displayName?: import(\"../config/config\")."
+                  "text": "[];\n                name: string;\n                provider?: import(\"../config/config\")."
                 },
                 {
                   "kind": "Reference",
-                  "text": "SystemPromptInput",
-                  "canonicalReference": "@genesislcap/ai-assistant!SystemPromptInput:type"
+                  "text": "ProviderInput",
+                  "canonicalReference": "@genesislcap/ai-assistant!ProviderInput:type"
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n                systemPrompt?: import(\"../config/config\")."
+                  "text": ";\n                chatInputDuringExecution?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatInputDuringExecutionMode",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatInputDuringExecutionMode:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";\n                description?: string;\n                fallback?: true;\n                displayName?: import(\"../config/config\")."
                 },
                 {
                   "kind": "Reference",
@@ -5502,12 +5511,12 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n                provider?: import(\"../config/config\")."
+                  "text": ";\n                systemPrompt?: import(\"../config/config\")."
                 },
                 {
                   "kind": "Reference",
-                  "text": "ProviderInput",
-                  "canonicalReference": "@genesislcap/ai-assistant!ProviderInput:type"
+                  "text": "SystemPromptInput",
+                  "canonicalReference": "@genesislcap/ai-assistant!SystemPromptInput:type"
                 },
                 {
                   "kind": "Content",
@@ -5529,34 +5538,34 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n                primerHistory?: "
+                  "text": ";\n                onUnresolvedTool?: import(\"../config/config\")."
                 },
                 {
                   "kind": "Reference",
-                  "text": "ChatMessage",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatMessage:interface"
+                  "text": "UnresolvedToolInput",
+                  "canonicalReference": "@genesislcap/ai-assistant!UnresolvedToolInput:type"
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n                subAgents?: "
+                  "text": ";\n                primerHistory?: "
                 },
                 {
                   "kind": "Reference",
-                  "text": "AgentConfig",
-                  "canonicalReference": "@genesislcap/ai-assistant!AgentConfig:type"
+                  "text": "ChatMessage",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatMessage:interface"
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n                chatInputDuringExecution?: "
+                  "text": "[];\n                subAgents?: "
                 },
                 {
                   "kind": "Reference",
-                  "text": "ChatInputDuringExecutionMode",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatInputDuringExecutionMode:type"
+                  "text": "AgentConfig",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentConfig:type"
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n                manualSelection?: import(\"../config/config\")."
+                  "text": "[];\n                manualSelection?: import(\"../config/config\")."
                 },
                 {
                   "kind": "Reference",
@@ -5565,97 +5574,43 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n            } | {\n                toolDefinitions: string | import(\"@genesislcap/foundation-ai\")."
-                },
-                {
-                  "kind": "Reference",
-                  "text": "ChatToolDefinition",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatToolDefinition:interface"
-                },
-                {
-                  "kind": "Content",
-                  "text": "[];\n                toolHandlers: any;\n                onActivate: any;\n                onDeactivate: any;\n                getDebugSnapshot: any;\n                fallback: true;\n                description?: never;\n                name: string;\n                displayName?: import(\"../config/config\")."
-                },
-                {
-                  "kind": "Reference",
-                  "text": "SystemPromptInput",
-                  "canonicalReference": "@genesislcap/ai-assistant!SystemPromptInput:type"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";\n                systemPrompt?: import(\"../config/config\")."
-                },
-                {
-                  "kind": "Reference",
-                  "text": "SystemPromptInput",
-                  "canonicalReference": "@genesislcap/ai-assistant!SystemPromptInput:type"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";\n                provider?: import(\"../config/config\")."
-                },
-                {
-                  "kind": "Reference",
-                  "text": "ProviderInput",
-                  "canonicalReference": "@genesislcap/ai-assistant!ProviderInput:type"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";\n                temperature?: import(\"../config/config\")."
-                },
-                {
-                  "kind": "Reference",
-                  "text": "TemperatureInput",
-                  "canonicalReference": "@genesislcap/ai-assistant!TemperatureInput:type"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";\n                toolChoice?: import(\"../config/config\")."
-                },
-                {
-                  "kind": "Reference",
-                  "text": "ToolChoiceInput",
-                  "canonicalReference": "@genesislcap/ai-assistant!ToolChoiceInput:type"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";\n                primerHistory?: "
+                  "text": ";\n                onActivate?: (ctx: import(\"../config/config\")."
                 },
                 {
                   "kind": "Reference",
-                  "text": "ChatMessage",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatMessage:interface"
+                  "text": "AgentLifecycleContext",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentLifecycleContext:interface"
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n                subAgents?: "
+                  "text": ") => void | "
                 },
                 {
                   "kind": "Reference",
-                  "text": "AgentConfig",
-                  "canonicalReference": "@genesislcap/ai-assistant!AgentConfig:type"
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n                chatInputDuringExecution?: "
+                  "text": "<void>;\n                onDeactivate?: (ctx: import(\"../config/config\")."
                 },
                 {
                   "kind": "Reference",
-                  "text": "ChatInputDuringExecutionMode",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatInputDuringExecutionMode:type"
+                  "text": "AgentLifecycleContext",
+                  "canonicalReference": "@genesislcap/ai-assistant!AgentLifecycleContext:interface"
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n                manualSelection?: import(\"../config/config\")."
+                  "text": ") => void | "
                 },
                 {
                   "kind": "Reference",
-                  "text": "ManualSelectionConfig",
-                  "canonicalReference": "@genesislcap/ai-assistant!ManualSelectionConfig:interface"
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n            })[];\n            activeSystemPrompt: string;\n            activePrimerHistory: "
+                  "text": "<void>;\n                getDebugSnapshot?: () => unknown;\n            }[];\n            activeSystemPrompt: string;\n            activePrimerHistory: "
                 },
                 {
                   "kind": "Reference",
@@ -5674,7 +5629,7 @@
               "isStatic": false,
               "returnTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 64
+                "endIndex": 54
               },
               "releaseTag": "Beta",
               "isProtected": false,
@@ -9630,6 +9585,51 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#onUnresolvedTool:member",
+              "docComment": "/**\n * Hook consulted when the model calls a tool that isn't dispatchable in the current state — a *stale* tool (valid in an earlier state of this agent) or an *unknown* one. Receives the current `state` alongside the attempted tool name and the currently dispatchable tools, so a machine-driven agent can return a step-aware redirect (e.g. \"that belongs to a later step — finish this one first\"). Return `undefined` to keep the framework default; a pre-init call also degrades to the default rather than throwing. See {@link UnresolvedToolContext}.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "onUnresolvedTool?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "(ctx: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "UnresolvedToolContext",
+                  "canonicalReference": "@genesislcap/ai-assistant!UnresolvedToolContext:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " & {\n        state: S;\n    }) => string | undefined | "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<string | undefined>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "onUnresolvedTool",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 6
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#primerHistory:member",
@@ -10974,6 +10974,149 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/ai-assistant!UnresolvedToolContext:interface",
+          "docComment": "/**\n * Context passed to an agent's `onUnresolvedTool` hook when the model calls a tool the driver cannot dispatch.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface UnresolvedToolContext "
+            }
+          ],
+          "fileUrlPath": "src/config/config.ts",
+          "releaseTag": "Beta",
+          "name": "UnresolvedToolContext",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!UnresolvedToolContext#availableTools:member",
+              "docComment": "/**\n * The tool names dispatchable right now, so the hook can steer the model back to a valid call.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "availableTools: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string[]"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "availableTools",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!UnresolvedToolContext#kind:member",
+              "docComment": "/**\n * Why the call could not be dispatched: - `'stale'` — the tool was advertised earlier this activation but is not part of the current step (e.g. a stateful agent has moved on). - `'unknown'` — the tool was never advertised this activation (a hallucinated name).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "kind: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "'stale' | 'unknown'"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "kind",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!UnresolvedToolContext#toolName:member",
+              "docComment": "/**\n * The tool name the model attempted to call.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "toolName: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "toolName",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/ai-assistant!UnresolvedToolInput:type",
+          "docComment": "/**\n * Optional per-agent hook consulted only on the already-failing unresolved-tool path — when the model calls a tool the driver cannot dispatch. Lets the agent replace the framework's default message with a context-aware redirect.\n *\n * Return a non-empty string to override the default tool-result message; return `undefined` (or an empty/whitespace string, or throw) to fall back to the framework default. The happy path is never affected. See {@link UnresolvedToolContext}.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type UnresolvedToolInput = "
+            },
+            {
+              "kind": "Content",
+              "text": "(ctx: "
+            },
+            {
+              "kind": "Reference",
+              "text": "UnresolvedToolContext",
+              "canonicalReference": "@genesislcap/ai-assistant!UnresolvedToolContext:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ") => string | undefined | "
+            },
+            {
+              "kind": "Reference",
+              "text": "Promise",
+              "canonicalReference": "!Promise:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<string | undefined>"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/config/config.ts",
+          "releaseTag": "Beta",
+          "name": "UnresolvedToolInput",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 6
+          }
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/ai-assistant!userIconSvg:var",

package/dist/ai-assistant.d.ts

@@ -578,6 +578,18 @@ declare interface BaseAgentConfig {
      * @beta
      */
     toolChoice?: ToolChoiceInput;
+    /**
+     * Optional hook consulted when the model calls a tool the driver cannot
+     * dispatch — either a *stale* tool (advertised earlier this activation but
+     * not part of the current step) or an *unknown* one (never advertised this
+     * activation). Return a context-aware redirect string to replace the
+     * framework's default message, or `undefined` to keep it. Consulted only on
+     * the already-failing unresolved-tool path; the happy path is unaffected.
+     * See {@link UnresolvedToolInput}.
+     *
+     * @beta
+     */
+    onUnresolvedTool?: UnresolvedToolInput;
     /**
      * Optional primer history prepended to every call (not visible to the user).
      * Used to establish agent identity and behavioural rules.
@@ -705,6 +717,14 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * sent to the model — stored `history` stays unchanged for UI and logging.
      */
     private providerHistoryTransform?;
+    /**
+     * Tool-declared condensation policies, keyed by tool-call id. Populated by
+     * `condenseWhen` (first-wins per call); read by `applyCondensation` before each
+     * provider call to collapse stale payloads from the model-bound history only.
+     * Accumulates across agents on a shared driver (a superseded read collapses no
+     * matter which agent made it) and is never cleared — it dies with the driver.
+     */
+    private readonly condensePolicies;
     /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
     private foldStack;
     /** Consecutive fold open/close ops without a real tool call. Reset on real tool execution. */
@@ -813,6 +833,13 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * call; top-level turns are `'auto'`).
      */
     private activeToolChoiceInput?;
+    /**
+     * Active agent's unresolved-tool hook, captured from `applyAgent`. Consulted
+     * only when a tool call cannot be dispatched (a stale or hallucinated name);
+     * `undefined` keeps the framework's default messages. See
+     * `resolveUnresolvedToolContent`.
+     */
+    private activeOnUnresolvedTool?;
     /**
      * Caches validated provider lookups per name within the current agent. Cleared
      * by `applyAgent` so each new agent's static/function-resolved names are
@@ -888,6 +915,15 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * each specialist turn so the shared driver runs with the right tools and prompt.
      */
     applyAgent(config: AgentConfig): void;
+    /**
+     * Resolve the tool-result content for an unresolved tool call. Consults the
+     * active agent's `onUnresolvedTool` hook (if any) with the attempted tool
+     * name, the failure `kind`, and the currently dispatchable tools, and returns
+     * the hook's non-empty string. Falls back to `fallback` when no hook is set,
+     * the hook returns nothing/empty, or the hook throws — so a misbehaving hook
+     * can never break tool dispatch.
+     */
+    private resolveUnresolvedToolContent;
     /**
      * Returns the most recently resolved provider name. Falls back to the
      * registry's default when no per-turn resolution has happened yet.
@@ -1045,6 +1081,10 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * Centralised here so fold shortcut dispatch and the main tool loop use the
      * same context without duplication.
      *
+     * @param active - The tool call this context belongs to (id + current loop
+     *   iteration). Threaded so `condenseWhen` can register against the right call
+     *   and stamp its age clock. Absent for dispatch paths with no addressable tool
+     *   call (e.g. the fold-close handler), where `condenseWhen` is a no-op.
      * @param traceCapture - Optional per-invocation slot. When provided, the trace
      *   from any sub-agent call is written here rather than to shared instance state,
      *   so parallel tool calls each capture their own trace independently.
@@ -1693,44 +1733,25 @@ export declare class FoundationAiAssistant extends GenesisElement {
         meta: {
             timestamp: string;
             host: string;
-            agentSummary: ({
+            agentSummary: {
                 toolDefinitions: string | ChatToolDefinition[];
-                toolHandlers: any;
-                onActivate: any;
-                onDeactivate: any;
-                getDebugSnapshot: any;
-                description: string;
-                fallback?: never;
-                excludeFromClassifier?: boolean;
                 name: string;
-                displayName?: SystemPromptInput;
-                systemPrompt?: SystemPromptInput;
                 provider?: ProviderInput;
-                temperature?: TemperatureInput;
-                toolChoice?: ToolChoiceInput;
-                primerHistory?: ChatMessage[];
-                subAgents?: AgentConfig[];
                 chatInputDuringExecution?: ChatInputDuringExecutionMode;
-                manualSelection?: ManualSelectionConfig;
-            } | {
-                toolDefinitions: string | ChatToolDefinition[];
-                toolHandlers: any;
-                onActivate: any;
-                onDeactivate: any;
-                getDebugSnapshot: any;
-                fallback: true;
-                description?: never;
-                name: string;
+                description?: string;
+                fallback?: true;
                 displayName?: SystemPromptInput;
                 systemPrompt?: SystemPromptInput;
-                provider?: ProviderInput;
                 temperature?: TemperatureInput;
                 toolChoice?: ToolChoiceInput;
+                onUnresolvedTool?: UnresolvedToolInput;
                 primerHistory?: ChatMessage[];
                 subAgents?: AgentConfig[];
-                chatInputDuringExecution?: ChatInputDuringExecutionMode;
                 manualSelection?: ManualSelectionConfig;
-            })[];
+                onActivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
+                onDeactivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
+                getDebugSnapshot?: () => unknown;
+            }[];
             activeSystemPrompt: string;
             activePrimerHistory: ChatMessage[];
             activeFoldStack: string[];
@@ -1958,7 +1979,7 @@ declare type MetaEventImportance = 'high' | 'normal' | 'low';
  * Catalogue of meta event names. This is the documented surface — extend it as
  * new events are wired in (Tier 2/3 lifecycle, interaction, provider events).
  */
-declare type MetaEventType = 'assistant.connected' | 'assistant.disconnected' | 'assistant.popout' | 'assistant.popin' | 'driver.created' | 'driver.wired' | 'driver.unwired' | 'state.changed' | 'turn.start' | 'turn.end' | 'turn.retry' | 'turn.error' | 'tool.failed' | 'tool.unresolved' | 'subagent.started' | 'subagent.completed' | 'subagent.failed' | 'agent.handoff' | 'agent.pinned' | 'agent.unpinned' | 'provider.selected' | 'interaction.requested' | 'interaction.resolved' | 'context.updated' | 'context.threshold-crossed' | 'panel.toggled' | 'attachment.added' | 'file.read-failed' | 'suggestions.failed';
+declare type MetaEventType = 'assistant.connected' | 'assistant.disconnected' | 'assistant.popout' | 'assistant.popin' | 'driver.created' | 'driver.wired' | 'driver.unwired' | 'state.changed' | 'turn.start' | 'turn.end' | 'turn.retry' | 'turn.error' | 'tool.failed' | 'tool.unresolved' | 'subagent.started' | 'subagent.completed' | 'subagent.failed' | 'agent.handoff' | 'agent.pinned' | 'agent.unpinned' | 'provider.selected' | 'interaction.requested' | 'interaction.resolved' | 'context.updated' | 'context.threshold-crossed' | 'context.condensed' | 'panel.toggled' | 'attachment.added' | 'file.read-failed' | 'suggestions.failed';
 
 /**
  * Orchestrates multiple specialist agents. Sits between `FoundationAiAssistant`
@@ -2260,6 +2281,19 @@ export declare interface StatefulAgentInit<S> {
      * for the default.
      */
     toolChoice?: ChatToolChoice | ((ctx: StatefulAgentContext<S>) => ChatToolChoice | Promise<ChatToolChoice>);
+    /**
+     * Hook consulted when the model calls a tool that isn't dispatchable in the
+     * current state — a *stale* tool (valid in an earlier state of this agent) or
+     * an *unknown* one. Receives the current `state` alongside the attempted tool
+     * name and the currently dispatchable tools, so a machine-driven agent can
+     * return a step-aware redirect (e.g. "that belongs to a later step — finish
+     * this one first"). Return `undefined` to keep the framework default; a
+     * pre-init call also degrades to the default rather than throwing.
+     * See {@link UnresolvedToolContext}.
+     */
+    onUnresolvedTool?: (ctx: UnresolvedToolContext & {
+        state: S;
+    }) => string | undefined | Promise<string | undefined>;
     /**
      * Optional getter for the debug-log snapshot. Defaults to auto-snapshotting
      * any property on `state` that looks like a foundation-state-machine
@@ -2497,6 +2531,44 @@ export declare interface TurnSnapshot {
     agentSnapshot?: unknown;
 }
 
+/**
+ * Context passed to an agent's `onUnresolvedTool` hook when the model calls a
+ * tool the driver cannot dispatch.
+ *
+ * @beta
+ */
+export declare interface UnresolvedToolContext {
+    /** The tool name the model attempted to call. */
+    toolName: string;
+    /**
+     * Why the call could not be dispatched:
+     * - `'stale'` — the tool was advertised earlier this activation but is not
+     *   part of the current step (e.g. a stateful agent has moved on).
+     * - `'unknown'` — the tool was never advertised this activation (a
+     *   hallucinated name).
+     */
+    kind: 'stale' | 'unknown';
+    /**
+     * The tool names dispatchable right now, so the hook can steer the model
+     * back to a valid call.
+     */
+    availableTools: string[];
+}
+
+/**
+ * Optional per-agent hook consulted only on the already-failing unresolved-tool
+ * path — when the model calls a tool the driver cannot dispatch. Lets the agent
+ * replace the framework's default message with a context-aware redirect.
+ *
+ * Return a non-empty string to override the default tool-result message; return
+ * `undefined` (or an empty/whitespace string, or throw) to fall back to the
+ * framework default. The happy path is never affected. See
+ * {@link UnresolvedToolContext}.
+ *
+ * @beta
+ */
+export declare type UnresolvedToolInput = (ctx: UnresolvedToolContext) => string | undefined | Promise<string | undefined>;
+
 /** Person silhouette — default user avatar. */
 export declare const userIconSvg = "<svg viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z\" fill=\"currentColor\"/></svg>";