@genesislcap/ai-assistant 14.451.3 → 14.451.4

package/dist/ai-assistant.d.ts

@@ -631,6 +631,21 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * hallucinated. Reset alongside `consecutiveUnknownToolCalls`.
      */
     private readonly recentUnknownToolNames;
+    /**
+     * Union of every tool name advertised at any point during the current agent
+     * activation. Lets the unknown-tool path tell a *stale* call (a real tool from
+     * an earlier state, now retired — or one an open exclusive fold is hiding)
+     * apart from a *hallucinated* one. Reset on agent swap in `applyAgent`.
+     */
+    private readonly everSeenToolNames;
+    /**
+     * Subset of the current unknown-tool streak that was stale (previously
+     * available) rather than hallucinated — surfaced separately on the
+     * `unknown-tool-limit` turn.error so triage can tell a state/prompt-design
+     * problem from a model that's inventing tools. Reset alongside
+     * `recentUnknownToolNames`.
+     */
+    private readonly recentStaleToolNames;
     private readonly maxFoldOperations;
     /** Sub-agents declared on the active agent config, keyed by name. */
     private subAgentsMap;
@@ -806,6 +821,17 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * to find which fold contains a given tool name. Returns the immediate parent fold name.
      */
     private findFoldContaining;
+    /**
+     * If an open fold is hiding a previously-available tool, return the name of
+     * the fold to close to start getting it back. Only exclusive folds hide tools
+     * (they replace the tool set on open rather than extending it), so a base tool
+     * that was visible before the fold opened now sits in a fold-stack frame's
+     * `previousHandlers` but not in the live handler map. Only the top fold's
+     * `close_` tool is active, so that's always the actionable next step — even
+     * when the tool lives further down the stack, closing repeatedly walks back to
+     * it. Returns null when no open fold accounts for the tool.
+     */
+    private foldHidingTool;
     /**
      * Install the fold's inner tool set, replacing (exclusive) or extending (non-exclusive)
      * the current tool set. Also injects the close tool. Does NOT touch the fold stack.
@@ -1579,7 +1605,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' | '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' | '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';
 
 /**
  * Orchestrates multiple specialist agents. Sits between `FoundationAiAssistant`

package/dist/dts/components/chat-driver/align-event-globals.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Test-only side effect: align the global `EventTarget` with jsdom's before any
+ * module that `extends EventTarget` is evaluated.
+ *
+ * The node test runner's jsdom setup installs `globalThis.CustomEvent` from
+ * jsdom but leaves `globalThis.EventTarget` as Node's native class. A class that
+ * `extends EventTarget` (e.g. {@link ChatDriver}) then inherits Node's native
+ * `dispatchEvent`, which rejects the jsdom `CustomEvent` instances it is handed
+ * ("The 'event' argument must be an instance of Event. Received an instance of
+ * CustomEvent"). Pointing `EventTarget` at jsdom's keeps the whole event family
+ * in one realm.
+ *
+ * No-op in a real browser, where `window.EventTarget === globalThis.EventTarget`
+ * already. Import this BEFORE importing anything that subclasses `EventTarget`.
+ */
+declare const jsdomWindow: {
+    EventTarget?: typeof EventTarget;
+};
+//# sourceMappingURL=align-event-globals.d.ts.map

package/dist/dts/components/chat-driver/align-event-globals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"align-event-globals.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/align-event-globals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,QAAA,MAAM,WAAW;kBAA6C,OAAO,WAAW;CAAY,CAAC"}

package/dist/dts/components/chat-driver/chat-driver.d.ts

@@ -122,6 +122,21 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * hallucinated. Reset alongside `consecutiveUnknownToolCalls`.
      */
     private readonly recentUnknownToolNames;
+    /**
+     * Union of every tool name advertised at any point during the current agent
+     * activation. Lets the unknown-tool path tell a *stale* call (a real tool from
+     * an earlier state, now retired — or one an open exclusive fold is hiding)
+     * apart from a *hallucinated* one. Reset on agent swap in `applyAgent`.
+     */
+    private readonly everSeenToolNames;
+    /**
+     * Subset of the current unknown-tool streak that was stale (previously
+     * available) rather than hallucinated — surfaced separately on the
+     * `unknown-tool-limit` turn.error so triage can tell a state/prompt-design
+     * problem from a model that's inventing tools. Reset alongside
+     * `recentUnknownToolNames`.
+     */
+    private readonly recentStaleToolNames;
     private readonly maxFoldOperations;
     /** Sub-agents declared on the active agent config, keyed by name. */
     private subAgentsMap;
@@ -297,6 +312,17 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * to find which fold contains a given tool name. Returns the immediate parent fold name.
      */
     private findFoldContaining;
+    /**
+     * If an open fold is hiding a previously-available tool, return the name of
+     * the fold to close to start getting it back. Only exclusive folds hide tools
+     * (they replace the tool set on open rather than extending it), so a base tool
+     * that was visible before the fold opened now sits in a fold-stack frame's
+     * `previousHandlers` but not in the live handler map. Only the top fold's
+     * `close_` tool is active, so that's always the actionable next step — even
+     * when the tool lives further down the stack, closing repeatedly walks back to
+     * it. Returns null when no open fold accounts for the tool.
+     */
+    private foldHidingTool;
     /**
      * Install the fold's inner tool set, replacing (exclusive) or extending (non-exclusive)
      * the current tool set. Also injects the close tool. Does NOT touch the fold stack.

package/dist/dts/components/chat-driver/chat-driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat-driver.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,WAAW,EAKX,yBAAyB,EAE1B,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EACV,WAAW,EAGX,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAkBxE,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,yBAAyB,CAAC;AAMhE;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;AAE9E;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gGAAgG;IAChG,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAQD;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,WAAY,YAAW,QAAQ;IAyI3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAKjC,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAGlC,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,UAAU;IAjJ7B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,IAAI,CAAS;IACrB,kFAAkF;IAClF,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,mBAAmB,CAQvB;IAEJ,OAAO,CAAC,YAAY,CAAC,CAAoB;IACzC;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAuB;IAC9C;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB,CAAC,CAE2B;IAC1D;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY,CAAmB;IACvC;;;;OAIG;IACH,OAAO,CAAC,mBAAmB,CAAC,CAEsB;IAClD,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAClC,OAAO,CAAC,WAAW,CAAC,CAAoB;IACxC;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB,CAAC,CAIjB;IAChB;;;OAGG;IACH,OAAO,CAAC,wBAAwB,CAAC,CAA4C;IAE7E,8EAA8E;IAC9E,OAAO,CAAC,SAAS,CAAwB;IACzC,8FAA8F;IAC9F,OAAO,CAAC,kBAAkB,CAAK;IAC/B,6FAA6F;IAC7F,OAAO,CAAC,2BAA2B,CAAK;IACxC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAqB;IAC5D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C,qEAAqE;IACrE,OAAO,CAAC,YAAY,CAAuC;IAC3D;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB,CAAkC;IAC5D;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB,CAAS;IACtC;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAsB;IAC3C,+FAA+F;IAC/F,OAAO,CAAC,eAAe,CAAK;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,gBAAgB,CAAC,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAC,CAAgB;IAC5C;;;;OAIG;IACH,OAAO,CAAC,qBAAqB,CAAiC;IAC9D,iFAAiF;IACjF,OAAO,CAAC,wBAAwB,CAAC,CAAS;IAC1C,wFAAwF;IACxF,OAAO,CAAC,0BAA0B,CAAC,CAAS;gBAGzB,gBAAgB,EAAE,kBAAkB,EACrD,YAAY,GAAE,iBAAsB,EACpC,eAAe,GAAE,oBAAyB,EAC1C,YAAY,CAAC,EAAE,iBAAiB,EAChC,aAAa,CAAC,EAAE,WAAW,EAAE,EACZ,iBAAiB,GAAE,MAAoC,EACxE,iBAAiB,GAAE,MAAoC,EACvD,gBAAgB,GAAE,MAAmC;IACrD,oFAAoF;IACnE,UAAU,GAAE,MAAW;IAuB1C;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IA4CrC;;;OAGG;IACH,qBAAqB,IAAI,MAAM;IAI/B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;;;;OAKG;YACW,sBAAsB;IA4BpC;;;OAGG;IACH,qBAAqB,IAAI;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS;IAIxD;;;OAGG;IACH,wBAAwB,IAAI,OAAO;IAInC;;;;;;OAMG;IACH,gBAAgB,IAAI,aAAa,CAAC,YAAY,CAAC;IAI/C;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;;OAGG;IACH,2BAA2B,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,GAAG,IAAI;IAIxF,UAAU,IAAI,aAAa,CAAC,WAAW,CAAC;IAIxC,aAAa,IAAI,SAAS,WAAW,EAAE;IAIvC,0DAA0D;IAC1D,kBAAkB,IAAI,MAAM,EAAE;IAIxB,cAAc,CAClB,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,eAAe,EAAE,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC;IAiHpB,MAAM,IAAI,OAAO;IAIjB;;;;;OAKG;IACI,2BAA2B,CAChC,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,yBAAyB,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3F,IAAI;IAIP;;;;;;;;;;;;;;;;OAgBG;IACU,kBAAkB,CAAC,CAAC,EAC/B,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,GAAG,EACT,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,CAAC,CAAC;IAuCb;;;OAGG;IACI,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI;IA0BnE;;;OAGG;IACI,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAS3C,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAyC/F;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IAsC3B;;;;;OAKG;YACW,cAAc;IA8F5B;;;OAGG;IACG,mBAAmB,CAAC,eAAe,CAAC,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA0CrF,wFAAwF;IACxF,OAAO,CAAC,OAAO;IAKf;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA+BxB,uFAAuF;IACvF,OAAO,CAAC,QAAQ;IAqChB,OAAO,CAAC,aAAa;IAQrB,8EAA8E;IAC9E,OAAO,CAAC,SAAS;IAWjB,mFAAmF;IACnF,OAAO,CAAC,2BAA2B;YAkCrB,WAAW;IAobzB,OAAO,CAAC,eAAe;CAoBxB"}
+{"version":3,"file":"chat-driver.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.ts"],"names":[],"mappings":"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"}

package/dist/dts/components/chat-driver/chat-driver.test.d.ts

@@ -0,0 +1,2 @@
+import './align-event-globals';
+//# sourceMappingURL=chat-driver.test.d.ts.map

package/dist/dts/components/chat-driver/chat-driver.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-driver.test.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.test.ts"],"names":[],"mappings":"AAiBA,OAAO,uBAAuB,CAAC"}

package/dist/dts/main/main.template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.template.d.ts","sourceRoot":"","sources":["../../../src/main/main.template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,OAAO,EAA2B,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAoIpD,gBAAgB;AAChB,eAAO,MAAM,6BAA6B,GACxC,oBAAoB,MAAM,KACzB,YAAY,CAAC,qBAAqB,CA8hBpC,CAAC"}
+{"version":3,"file":"main.template.d.ts","sourceRoot":"","sources":["../../../src/main/main.template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,OAAO,EAA2B,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAwIpD,gBAAgB;AAChB,eAAO,MAAM,6BAA6B,GACxC,oBAAoB,MAAM,KACzB,YAAY,CAAC,qBAAqB,CA8hBpC,CAAC"}

package/dist/dts/state/debug-event-log.d.ts

@@ -27,7 +27,7 @@
  * 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).
  */
-export 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' | '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';
+export 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' | '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';
 /**
  * How much a reader should care about an event — lets a consumer (or an AI
  * agent) filter the timeline: skip `low` UI/bookkeeping noise, skim `normal`
@@ -74,7 +74,8 @@ export declare function recordMetaEvent(key: string, type: MetaEventType, detail
  * - `exception`              — an uncaught error escaped the tool loop (catch-all).
  * - `malformed-function-call`— the provider returned an unparseable tool call.
  * - `empty-response`         — the model returned no content and no tool calls.
- * - `unknown-tool-limit`     — the model repeatedly called tools that don't exist.
+ * - `unknown-tool-limit`     — the model repeatedly called tools it couldn't dispatch,
+ *                              whether hallucinated or stale (real earlier, retired now).
  * - `max-iterations`         — the tool loop hit its iteration cap.
  */
 export type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations';

package/dist/dts/state/debug-event-log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debug-event-log.d.ts","sourceRoot":"","sources":["../../../src/state/debug-event-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAErB,qBAAqB,GACrB,wBAAwB,GACxB,kBAAkB,GAClB,iBAAiB,GAEjB,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAEhB,eAAe,GACf,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,aAAa,GAEb,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,mBAAmB,GAEnB,uBAAuB,GACvB,sBAAsB,GAEtB,iBAAiB,GACjB,2BAA2B,GAE3B,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,EAAE,mBAAmB,CA4B5E,CAAC;AAEF,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,IAAI,EAAE,aAAa,CAAC;IACpB,6EAA6E;IAC7E,UAAU,EAAE,mBAAmB,CAAC;IAChC,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAmBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAyBN;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,yBAAyB,GACzB,gBAAgB,GAChB,oBAAoB,GACpB,gBAAgB,CAAC;AAErB;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAEN;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAEnE;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAW7C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}
+{"version":3,"file":"debug-event-log.d.ts","sourceRoot":"","sources":["../../../src/state/debug-event-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAErB,qBAAqB,GACrB,wBAAwB,GACxB,kBAAkB,GAClB,iBAAiB,GAEjB,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAEhB,eAAe,GACf,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,aAAa,GACb,iBAAiB,GAEjB,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,mBAAmB,GAEnB,uBAAuB,GACvB,sBAAsB,GAEtB,iBAAiB,GACjB,2BAA2B,GAE3B,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,EAAE,mBAAmB,CA6B5E,CAAC;AAEF,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,IAAI,EAAE,aAAa,CAAC;IACpB,6EAA6E;IAC7E,UAAU,EAAE,mBAAmB,CAAC;IAChC,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAmBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAyBN;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,yBAAyB,GACzB,gBAAgB,GAChB,oBAAoB,GACpB,gBAAgB,CAAC;AAErB;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAEN;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAEnE;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAW7C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/esm/components/chat-driver/align-event-globals.js

@@ -0,0 +1,23 @@
+/**
+ * Test-only side effect: align the global `EventTarget` with jsdom's before any
+ * module that `extends EventTarget` is evaluated.
+ *
+ * The node test runner's jsdom setup installs `globalThis.CustomEvent` from
+ * jsdom but leaves `globalThis.EventTarget` as Node's native class. A class that
+ * `extends EventTarget` (e.g. {@link ChatDriver}) then inherits Node's native
+ * `dispatchEvent`, which rejects the jsdom `CustomEvent` instances it is handed
+ * ("The 'event' argument must be an instance of Event. Received an instance of
+ * CustomEvent"). Pointing `EventTarget` at jsdom's keeps the whole event family
+ * in one realm.
+ *
+ * No-op in a real browser, where `window.EventTarget === globalThis.EventTarget`
+ * already. Import this BEFORE importing anything that subclasses `EventTarget`.
+ */
+const jsdomWindow = globalThis.window;
+if ((jsdomWindow === null || jsdomWindow === void 0 ? void 0 : jsdomWindow.EventTarget) && globalThis.EventTarget !== jsdomWindow.EventTarget) {
+    Object.defineProperty(globalThis, 'EventTarget', {
+        value: jsdomWindow.EventTarget,
+        configurable: true,
+        writable: true,
+    });
+}

package/dist/esm/components/chat-driver/chat-driver.js

@@ -60,6 +60,21 @@ export class ChatDriver extends EventTarget {
          * hallucinated. Reset alongside `consecutiveUnknownToolCalls`.
          */
         this.recentUnknownToolNames = new Set();
+        /**
+         * Union of every tool name advertised at any point during the current agent
+         * activation. Lets the unknown-tool path tell a *stale* call (a real tool from
+         * an earlier state, now retired — or one an open exclusive fold is hiding)
+         * apart from a *hallucinated* one. Reset on agent swap in `applyAgent`.
+         */
+        this.everSeenToolNames = new Set();
+        /**
+         * Subset of the current unknown-tool streak that was stale (previously
+         * available) rather than hallucinated — surfaced separately on the
+         * `unknown-tool-limit` turn.error so triage can tell a state/prompt-design
+         * problem from a model that's inventing tools. Reset alongside
+         * `recentUnknownToolNames`.
+         */
+        this.recentStaleToolNames = new Set();
         /** Sub-agents declared on the active agent config, keyed by name. */
         this.subAgentsMap = new Map();
         /**
@@ -156,6 +171,10 @@ export class ChatDriver extends EventTarget {
         // Reset fold state when agent changes — each specialist starts fresh
         this.foldStack = [];
         this.consecutiveFoldOps = 0;
+        // Forget the previous agent's tools — "previously available" is scoped to
+        // the current activation, so a stateful agent accumulates its tools across
+        // states while a swap to a different specialist starts clean.
+        this.everSeenToolNames.clear();
     }
     /**
      * Returns the most recently resolved provider name. Falls back to the
@@ -714,6 +733,22 @@ export class ChatDriver extends EventTarget {
         }
         return null;
     }
+    /**
+     * If an open fold is hiding a previously-available tool, return the name of
+     * the fold to close to start getting it back. Only exclusive folds hide tools
+     * (they replace the tool set on open rather than extending it), so a base tool
+     * that was visible before the fold opened now sits in a fold-stack frame's
+     * `previousHandlers` but not in the live handler map. Only the top fold's
+     * `close_` tool is active, so that's always the actionable next step — even
+     * when the tool lives further down the stack, closing repeatedly walks back to
+     * it. Returns null when no open fold accounts for the tool.
+     */
+    foldHidingTool(toolName) {
+        if (this.foldStack.length === 0)
+            return null;
+        const hidden = this.foldStack.some((f) => f.previousHandlers[toolName]);
+        return hidden ? this.foldStack[this.foldStack.length - 1].foldName : null;
+    }
     /**
      * Install the fold's inner tool set, replacing (exclusive) or extending (non-exclusive)
      * the current tool set. Also injects the close tool. Does NOT touch the fold stack.
@@ -820,7 +855,7 @@ export class ChatDriver extends EventTarget {
     // oxlint-disable-next-line complexity
     runToolLoop(userInput, attachments, transientPrimer) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
             if (!this.systemPrompt) {
                 logger.warn('ChatDriver: no systemPrompt set. The assistant will have no instructions — provide a systemPrompt via agents config or the foundation-ai-assistant property.');
             }
@@ -860,6 +895,12 @@ export class ChatDriver extends EventTarget {
                     // oxlint-disable-next-line no-await-in-loop
                     this.toolHandlers = yield this.toolHandlersFactory(promptCtx);
                 }
+                // Record everything advertised this turn so the unknown-tool path can tell
+                // a stale tool (real earlier, retired now) from a hallucinated one. Runs
+                // for both the static and factory cases; folds also flow through here as
+                // their inner tools become visible on the iteration after they open.
+                for (const def of this.toolDefinitions)
+                    this.everSeenToolNames.add(def.name);
                 const resolvedSystemPrompt = typeof this.systemPrompt === 'function'
                     ? // oxlint-disable-next-line no-await-in-loop
                         yield this.systemPrompt(promptCtx)
@@ -991,6 +1032,9 @@ export class ChatDriver extends EventTarget {
                 }, [[], []]);
                 const executedById = new Map();
                 const unknownToolIds = new Set();
+                // Subset of unknownToolIds that were stale (previously available) rather
+                // than hallucinated — drives the `stale` UI flag back-patched below.
+                const staleToolIds = new Set();
                 let anyRealToolExecuted = false;
                 let hitUnknownToolLimit = false;
                 if (toolCalls.length > 0) {
@@ -1038,22 +1082,73 @@ export class ChatDriver extends EventTarget {
                             const containingFold = this.findFoldContaining(tc.name);
                             if (containingFold) {
                                 logger.debug(`ChatDriver: model called folded tool "${tc.name}" — guiding to open "${containingFold}"`);
+                                recordMetaEvent(this.sessionKey, 'tool.unresolved', {
+                                    tool: tc.name,
+                                    agent: this.activeAgentName,
+                                    kind: 'folded',
+                                    fold: containingFold,
+                                });
                                 executedById.set(tc.id, {
                                     toolCallId: tc.id,
                                     content: `"${tc.name}" is not directly available. It is inside the "${containingFold}" fold. Call ${containingFold} first to access it.`,
                                 });
                                 // Guidance does not count as a real iteration or fold op
                                 iterations -= 1;
+                                return;
                             }
-                            else {
+                            // Not in any registered fold. If the tool was advertised earlier
+                            // in this agent's lifetime it's *stale* (a stateful agent moved on,
+                            // or an exclusive fold is hiding it) rather than hallucinated — a
+                            // distinction worth making, because the model should stop retrying
+                            // a retired tool rather than treat the failure as a typo. Stale
+                            // calls still count toward the same unknown-tool limit (loop
+                            // protection); only the guidance and telemetry differ.
+                            if (this.everSeenToolNames.has(tc.name)) {
                                 this.consecutiveUnknownToolCalls += 1;
-                                logger.warn(`ChatDriver: no handler registered for tool "${tc.name}" (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}). Available tools: ${Object.keys(this.toolHandlers).join(', ') || '(none)'}`);
-                                executedById.set(tc.id, { toolCallId: tc.id, content: `Unknown tool: ${tc.name}` });
+                                const hidingFold = this.foldHidingTool(tc.name);
+                                let content;
+                                if (hidingFold) {
+                                    content = `"${tc.name}" is not available while the "${hidingFold}" fold is open. Call close_${hidingFold} to return to the previous set of tools, then call ${tc.name}.`;
+                                    logger.warn(`ChatDriver: tool "${tc.name}" is hidden behind open fold "${hidingFold}" (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS})`);
+                                }
+                                else {
+                                    content = `"${tc.name}" was available earlier but is not part of the current step — that step is complete, so do not call it again. Continue with the tools available now: ${Object.keys(this.toolHandlers).join(', ') || '(none)'}.`;
+                                    logger.warn(`ChatDriver: stale tool "${tc.name}" — advertised earlier this activation but retired in the current state (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS})`);
+                                }
+                                recordMetaEvent(this.sessionKey, 'tool.unresolved', {
+                                    tool: tc.name,
+                                    agent: this.activeAgentName,
+                                    kind: hidingFold ? 'fold-hidden' : 'stale',
+                                    fold: hidingFold !== null && hidingFold !== void 0 ? hidingFold : undefined,
+                                    consecutive: this.consecutiveUnknownToolCalls,
+                                    max: DEFAULT_MAX_UNKNOWN_TOOL_CALLS,
+                                });
+                                executedById.set(tc.id, { toolCallId: tc.id, content });
                                 unknownToolIds.add(tc.id);
+                                staleToolIds.add(tc.id);
                                 this.recentUnknownToolNames.add(tc.name);
+                                this.recentStaleToolNames.add(tc.name);
                                 if (this.consecutiveUnknownToolCalls >= DEFAULT_MAX_UNKNOWN_TOOL_CALLS) {
                                     hitUnknownToolLimit = true;
                                 }
+                                return;
+                            }
+                            // Never advertised — a hallucinated tool name.
+                            this.consecutiveUnknownToolCalls += 1;
+                            logger.warn(`ChatDriver: no handler registered for tool "${tc.name}" (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}). Available tools: ${Object.keys(this.toolHandlers).join(', ') || '(none)'}`);
+                            recordMetaEvent(this.sessionKey, 'tool.unresolved', {
+                                tool: tc.name,
+                                agent: this.activeAgentName,
+                                kind: 'unknown',
+                                consecutive: this.consecutiveUnknownToolCalls,
+                                max: DEFAULT_MAX_UNKNOWN_TOOL_CALLS,
+                                availableTools: Object.keys(this.toolHandlers),
+                            });
+                            executedById.set(tc.id, { toolCallId: tc.id, content: `Unknown tool: ${tc.name}` });
+                            unknownToolIds.add(tc.id);
+                            this.recentUnknownToolNames.add(tc.name);
+                            if (this.consecutiveUnknownToolCalls >= DEFAULT_MAX_UNKNOWN_TOOL_CALLS) {
+                                hitUnknownToolLimit = true;
                             }
                             return;
                         }
@@ -1089,6 +1184,7 @@ export class ChatDriver extends EventTarget {
                     this.consecutiveFoldOps = 0;
                     this.consecutiveUnknownToolCalls = 0;
                     this.recentUnknownToolNames.clear();
+                    this.recentStaleToolNames.clear();
                 }
                 // Tag tool calls with fold UI metadata before appending results
                 const foldPath = this.foldStack.map((f) => f.foldName);
@@ -1134,7 +1230,10 @@ export class ChatDriver extends EventTarget {
                                     ? 'close'
                                     : undefined, 
                             // Use the fold path that was active at the START of this iteration (before any opens/closes)
-                            foldPath: !isFoldOpen && !isFoldClose && foldPath.length > 0 ? foldPath : undefined, unknown: isUnknown || undefined, availableTools: isUnknown ? availableToolNames : undefined, subAgentTrace: (_e = executedById.get(tc.id)) === null || _e === void 0 ? void 0 : _e.subAgentTrace });
+                            foldPath: !isFoldOpen && !isFoldClose && foldPath.length > 0 ? foldPath : undefined, unknown: isUnknown || undefined, availableTools: isUnknown ? availableToolNames : undefined, 
+                            // Distinguish a retired tool from a hallucinated one so the UI can
+                            // say "no longer available here" rather than "does not exist".
+                            stale: staleToolIds.has(tc.id) || undefined, subAgentTrace: (_e = executedById.get(tc.id)) === null || _e === void 0 ? void 0 : _e.subAgentTrace });
                     });
                     this.history[tcMsgIdx] = Object.assign(Object.assign({}, tcMsg), { toolCalls: annotatedCalls });
                     this.dispatchEvent(new CustomEvent('history-updated', {
@@ -1151,10 +1250,25 @@ export class ChatDriver extends EventTarget {
                                 .map((tc) => tc.name),
                         ]),
                     ];
+                    // Stale tools were real earlier this activation; hallucinated tools
+                    // never existed. The hard stop counts both the same way, but the split
+                    // tells a triager whether the cause is a state/prompt-design problem
+                    // (stale) or a model inventing tool names (hallucinated).
+                    const staleTools = [
+                        ...new Set([
+                            ...this.recentStaleToolNames,
+                            ...((_j = response.toolCalls) !== null && _j !== void 0 ? _j : [])
+                                .filter((tc) => staleToolIds.has(tc.id))
+                                .map((tc) => tc.name),
+                        ]),
+                    ];
+                    const hallucinatedTools = unknownTools.filter((t) => !staleTools.includes(t));
                     recordTurnError(this.sessionKey, 'unknown-tool-limit', {
                         agent: this.activeAgentName,
                         provider: this.lastResolvedProviderName,
                         unknownTools,
+                        staleTools,
+                        hallucinatedTools,
                         availableTools: Object.keys(this.toolHandlers),
                     });
                     this.appendToHistory({

package/dist/esm/components/chat-driver/chat-driver.test.js

@@ -0,0 +1,196 @@
+import { __awaiter } from "tslib";
+import { isChatToolCallUnknown } from '@genesislcap/foundation-ai';
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { agenticActivityBus } from '../../channel/ai-activity-bus';
+import { clearMetaEventRegistry, getMetaEvents } from '../../state/debug-event-log';
+import { createToolFold } from '../../utils/tool-fold';
+// Side-effect import — MUST come before `./chat-driver` so the driver subclasses
+// jsdom's EventTarget rather than Node's native one (see the file). None of the
+// imports above pull in the driver, so its realm is still set before evaluation.
+import './align-event-globals';
+import { ChatDriver } from './chat-driver';
+const scriptedProvider = (responses) => {
+    const queue = [...responses];
+    const advertisedPerCall = [];
+    return {
+        advertisedPerCall,
+        chat: (_history, _userMessage, options) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b;
+            advertisedPerCall.push(((_a = options === null || options === void 0 ? void 0 : options.tools) !== null && _a !== void 0 ? _a : []).map((t) => t.name));
+            // Once the script is exhausted, end the turn with a plain text reply.
+            return (_b = queue.shift()) !== null && _b !== void 0 ? _b : { role: 'assistant', content: 'done' };
+        }),
+    };
+};
+const makeRegistry = (provider) => ({
+    get: () => provider,
+    default: () => provider,
+    defaultName: () => 'test',
+    names: () => ['test'],
+    getStatus: () => __awaiter(void 0, void 0, void 0, function* () { return null; }),
+    listStatuses: () => __awaiter(void 0, void 0, void 0, function* () { return []; }),
+});
+const def = (name) => ({
+    name,
+    description: `${name} tool`,
+    parameters: { type: 'object', properties: {} },
+});
+/** An assistant turn that calls a single tool. `content` is empty so the driver
+ * does not treat it as a thinking step (which would split it into two messages). */
+const callsTool = (name, id) => ({
+    role: 'assistant',
+    content: '',
+    toolCalls: [{ id, name, args: {} }],
+});
+const agent = (overrides) => (Object.assign({ description: 'test agent' }, overrides));
+const makeDriver = (config, provider, sessionKey = '') => {
+    const driver = new ChatDriver(makeRegistry(provider), {}, [], undefined, undefined, 50, 5, undefined, sessionKey);
+    driver.applyAgent(config);
+    return driver;
+};
+/** All tool calls across the whole conversation, flattened. */
+const allToolCalls = (driver) => driver.getHistory().flatMap((m) => { var _a; return (_a = m.toolCalls) !== null && _a !== void 0 ? _a : []; });
+/** Tool-result message contents, in order. */
+const toolResultContents = (driver) => driver
+    .getHistory()
+    .filter((m) => m.role === 'tool' && m.toolResult)
+    .map((m) => m.toolResult.content);
+/** `tool.unresolved` meta-event details recorded for a session (download-log surface). */
+const unresolvedEvents = (sessionKey) => getMetaEvents(sessionKey)
+    .filter((e) => e.type === 'tool.unresolved')
+    .map((e) => { var _a; return (_a = e.detail) !== null && _a !== void 0 ? _a : {}; });
+// ---------------------------------------------------------------------------
+// stale tool detection — stateful agent advances past a tool's state
+// ---------------------------------------------------------------------------
+const stale = createLogicSuite('ChatDriver stale-tool detection');
+// The driver imports the `agenticActivityBus` singleton, which opens a
+// BroadcastChannel at module load. An open channel keeps the test page alive
+// and hangs the runner, so close it once the suite finishes.
+stale.after(() => {
+    agenticActivityBus.close();
+});
+stale('guides the model when it calls a tool that an earlier state exposed', () => __awaiter(void 0, void 0, void 0, function* () {
+    // State A exposes tool_a; calling it advances to state B, which exposes only
+    // tool_b. A factory-form agent narrows the tool set per turn, mirroring how
+    // `defineStatefulAgent` works.
+    let state = 'A';
+    const config = agent({
+        name: 'Stateful',
+        toolDefinitions: () => (state === 'A' ? [def('tool_a')] : [def('tool_b')]),
+        toolHandlers: () => state === 'A'
+            ? {
+                tool_a: () => __awaiter(void 0, void 0, void 0, function* () {
+                    state = 'B';
+                    return 'advanced to B';
+                }),
+            }
+            : { tool_b: () => __awaiter(void 0, void 0, void 0, function* () { return 'b done'; }) },
+    });
+    const provider = scriptedProvider([
+        callsTool('tool_a', 't1'), // real — advances A -> B
+        callsTool('tool_a', 't2'), // stale — tool_a no longer in state B
+        callsTool('tool_b', 't3'), // real — valid in state B
+    ]);
+    const sessionKey = 'stale-meta-test';
+    const driver = makeDriver(config, provider, sessionKey);
+    const result = yield driver.sendMessage('go');
+    assert.is(result.reason, 'done');
+    // The per-state narrowing actually happened: tool_a advertised first, tool_b later.
+    assert.equal(provider.advertisedPerCall[0], ['tool_a']);
+    assert.ok(provider.advertisedPerCall.some((tools) => tools.includes('tool_b') && !tools.includes('tool_a')), 'a later turn should advertise tool_b without tool_a');
+    // The retried tool_a got stale guidance — not "Unknown tool".
+    const staleGuidance = toolResultContents(driver).find((c) => c.includes('was available earlier but is not part of the current step'));
+    assert.ok(staleGuidance, 'a previously-available tool should receive stale guidance');
+    assert.not.ok(toolResultContents(driver).some((c) => c.startsWith('Unknown tool:')), 'a previously-available tool must not be reported as a hallucination');
+    // The retried call is flagged unknown + stale for the UI.
+    const retried = allToolCalls(driver).filter((tc) => tc.name === 'tool_a' && isChatToolCallUnknown(tc));
+    assert.is(retried.length, 1, 'exactly one tool_a call should be flagged unknown');
+    assert.ok(isChatToolCallUnknown(retried[0]) && retried[0].stale === true, 'and marked stale');
+    // The occurrence is recorded to the meta-event log for the download log.
+    assert.ok(unresolvedEvents(sessionKey).some((d) => d.kind === 'stale' && d.tool === 'tool_a'), 'a stale tool.unresolved meta event should be recorded');
+}));
+stale('reports a never-seen tool as a hallucinated unknown tool', () => __awaiter(void 0, void 0, void 0, function* () {
+    const config = agent({
+        name: 'Static',
+        toolDefinitions: [def('real_tool')],
+        toolHandlers: { real_tool: () => __awaiter(void 0, void 0, void 0, function* () { return 'ok'; }) },
+    });
+    const provider = scriptedProvider([callsTool('made_up', 'm1')]);
+    const sessionKey = 'hallucination-meta-test';
+    const driver = makeDriver(config, provider, sessionKey);
+    yield driver.sendMessage('go');
+    assert.ok(toolResultContents(driver).includes('Unknown tool: made_up'), 'a tool never advertised should be reported as unknown');
+    const call = allToolCalls(driver).find((tc) => tc.name === 'made_up');
+    assert.ok(call && isChatToolCallUnknown(call), 'the call should be flagged unknown');
+    assert.not.ok(call.stale, 'a hallucinated tool must NOT be flagged stale');
+    assert.ok(unresolvedEvents(sessionKey).some((d) => d.kind === 'unknown' && d.tool === 'made_up'), 'an unknown tool.unresolved meta event should be recorded');
+}));
+stale('points the model at the close tool when an exclusive fold hides a base tool', () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    const fold = createToolFold({
+        name: 'my_fold',
+        tools: [def('inner_tool')],
+        handlers: { inner_tool: () => __awaiter(void 0, void 0, void 0, function* () { return 'inner done'; }) },
+        // exclusive defaults to true — opening it removes base_tool from the set.
+    });
+    const config = agent({
+        name: 'Folded',
+        toolDefinitions: [def('base_tool'), fold.definition],
+        toolHandlers: Object.assign({ base_tool: () => __awaiter(void 0, void 0, void 0, function* () { return 'base done'; }) }, fold.handler),
+    });
+    const provider = scriptedProvider([
+        callsTool('my_fold', 'f1'), // open the exclusive fold — base_tool now hidden
+        callsTool('base_tool', 'b1'), // hidden behind the open fold
+    ]);
+    const sessionKey = 'fold-meta-test';
+    const driver = makeDriver(config, provider, sessionKey);
+    yield driver.sendMessage('go');
+    // Target the base_tool result specifically — the fold-open result also
+    // mentions my_fold, so match on the tool call id rather than substring.
+    const guidance = (_b = (_a = driver
+        .getHistory()
+        .find((m) => { var _a; return m.role === 'tool' && ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 'b1'; })) === null || _a === void 0 ? void 0 : _a.toolResult) === null || _b === void 0 ? void 0 : _b.content;
+    assert.ok(guidance, 'calling a fold-hidden tool should produce guidance');
+    assert.match(guidance, /not available while the "my_fold" fold is open/);
+    assert.match(guidance, /close_my_fold/);
+    const hidden = allToolCalls(driver).find((tc) => tc.name === 'base_tool' && isChatToolCallUnknown(tc));
+    assert.ok(hidden && isChatToolCallUnknown(hidden) && hidden.stale === true, 'the hidden call is stale');
+    assert.ok(unresolvedEvents(sessionKey).some((d) => d.kind === 'fold-hidden' && d.tool === 'base_tool' && d.fold === 'my_fold'), 'a fold-hidden tool.unresolved meta event should be recorded');
+}));
+stale('splits stale vs hallucinated tools on the unknown-tool-limit error', () => __awaiter(void 0, void 0, void 0, function* () {
+    const sessionKey = 'stale-limit-test';
+    clearMetaEventRegistry();
+    let state = 'A';
+    const config = agent({
+        name: 'Stateful',
+        toolDefinitions: () => (state === 'A' ? [def('tool_a')] : [def('tool_b')]),
+        toolHandlers: () => state === 'A'
+            ? {
+                tool_a: () => __awaiter(void 0, void 0, void 0, function* () {
+                    state = 'B';
+                    return 'advanced to B';
+                }),
+            }
+            : { tool_b: () => __awaiter(void 0, void 0, void 0, function* () { return 'b done'; }) },
+    });
+    // One real call to advance to B, then 5 consecutive stale calls — the 5th
+    // trips DEFAULT_MAX_UNKNOWN_TOOL_CALLS and ends the turn.
+    const provider = scriptedProvider([
+        callsTool('tool_a', 'real'),
+        ...Array.from({ length: 5 }, (_unused, i) => callsTool('tool_a', `stale-${i}`)),
+    ]);
+    const driver = makeDriver(config, provider, sessionKey);
+    const result = yield driver.sendMessage('go');
+    assert.is(result.reason, 'done');
+    const limitError = getMetaEvents(sessionKey).find((e) => { var _a; return e.type === 'turn.error' && ((_a = e.detail) === null || _a === void 0 ? void 0 : _a.reason) === 'unknown-tool-limit'; });
+    assert.ok(limitError, 'hitting the limit should record an unknown-tool-limit turn.error');
+    const detail = limitError.detail;
+    assert.equal(detail.staleTools, ['tool_a'], 'tool_a should be classified as stale');
+    assert.equal(detail.hallucinatedTools, [], 'nothing was hallucinated');
+    // Every stale attempt — not just the final limit error — is in the download log.
+    assert.is(unresolvedEvents(sessionKey).filter((d) => d.kind === 'stale').length, 5, 'each stale attempt should be recorded as its own tool.unresolved event');
+    // The user-facing turn ends with the apology, not a crash.
+    const last = driver.getHistory().at(-1);
+    assert.ok((last === null || last === void 0 ? void 0 : last.role) === 'assistant' && last.content.startsWith("I'm sorry"));
+}));
+stale.run();

package/dist/esm/main/main.template.js

@@ -20,7 +20,11 @@ import { ANIMATION_DEFS } from './main.types';
 function unknownToolPayload(tc) {
     if (!isChatToolCallUnknown(tc))
         return '';
-    const lines = [`${tc.name} — tool does not exist`];
+    // A stale tool was real earlier in this agent's lifetime but isn't available
+    // in the current state — distinct from a hallucinated name that never existed.
+    const lines = [
+        tc.stale ? `${tc.name} — no longer available at this step` : `${tc.name} — tool does not exist`,
+    ];
     if (tc.availableTools.length > 0) {
         lines.push('Available tools:');
         tc.availableTools.forEach((t) => lines.push(`  • ${t}`));