@genesislcap/ai-assistant 15.84.3 → 15.85.0

package/dist/chat-driver.mjs

@@ -4410,7 +4410,7 @@ function toolCallIdsIn(history) {
   }
   return ids;
 }
-function snapshotCondensePolicies(policies, clocks, history) {
+function snapshotCondensePolicies(policies, clocks, history, suspended = /* @__PURE__ */ new Map()) {
   if (policies.size === 0) return [];
   const present = toolCallIdsIn(history);
   const out = [];
@@ -4425,8 +4425,11 @@ function snapshotCondensePolicies(policies, clocks, history) {
         // the clamp only stops a malformed entry from being written out as "the future".
         modelCalls: Math.max(0, clocks.modelCall - entry.iteration),
         turns: Math.max(0, clocks.turn - entry.turn),
-        activations: Math.max(0, clocks.activation - entry.activation),
-        phases: Math.max(0, clocks.phaseEpoch - entry.phaseEpoch)
+        activations: suspended.has(entry.activation) ? 0 : Math.max(0, clocks.activation - entry.activation),
+        phases: Math.max(
+          0,
+          (suspended.get(entry.activation) ?? clocks.phaseEpoch) - entry.phaseEpoch
+        )
       }
     });
   }
@@ -4546,7 +4549,7 @@ function applyCondensation(history, policies, ctx, onCondensed) {
       // backstop, when the whole activation has ended, so a phase boundary that
       // is never declared still collapses at `agentEnd` rather than never.
       case "phaseEnd":
-        return ctx.phaseEnded(entry.phaseEpoch) || ctx.activationEnded(entry.activation);
+        return ctx.phaseEnded(entry.phaseEpoch, entry.activation) || ctx.activationEnded(entry.activation);
       default:
         return latestByKey.get(trig.by) !== toolCallId;
     }
@@ -4921,6 +4924,17 @@ var AgentSession = class {
     this.restoredStates = {};
     /** The tail of the activation queue — see {@link AgentSession.activate}. */
     this.activation = Promise.resolve();
+    /**
+     * Callers waiting in a hand-off (GENC-1737), oldest first: still live, so never deactivated by
+     * the hand-off, and resumed without `onActivate`. Empty after a reload, when a caller has no live
+     * state and is activated again from its saved state instead.
+     */
+    this.suspended = [];
+    /**
+     * The `data` of the hand-off that activated each agent (GENC-1737), for its tool handlers: kept
+     * while it is active or waits as a caller, and dropped when its activation ends.
+     */
+    this.handOffData = /* @__PURE__ */ new Map();
   }
   /** The active agent, or `undefined` before the first activation and after a release. */
   getActive() {
@@ -4962,6 +4976,84 @@ var AgentSession = class {
   hasRestoredState(agentName) {
     return this.restoredStates[agentName] !== void 0;
   }
+  /** The `data` of the hand-off that activated `agentName`, if one did and carried any. */
+  getHandOffData(agentName) {
+    return this.handOffData.get(agentName);
+  }
+  /** Record the `data` a hand-off activated `agentName` with, or restore it; `undefined` drops it. */
+  setHandOffData(agentName, data) {
+    if (data === void 0) this.handOffData.delete(agentName);
+    else this.handOffData.set(agentName, data);
+  }
+  /**
+   * Drop the flow lock and leave the active agent active (GENC-1737): a plain agent holding it with
+   * no hand-off behind it is done once its turn ends.
+   */
+  dropFlowLock() {
+    if (this.flowOwner === null) return;
+    this.flowOwner = null;
+    this.reportTransition({
+      previousAgent: this.active,
+      switched: false,
+      flowOwnerChangedTo: null
+    });
+  }
+  /** The callers waiting in a hand-off whose state is live, oldest first. */
+  getSuspended() {
+    return this.suspended;
+  }
+  /**
+   * Make `target` active for a hand-off (GENC-1737), holding the flow lock whatever kind of agent
+   * it is, since a waiting caller depends on it. With `suspendCaller` the active agent waits:
+   * it is not deactivated and keeps its state. Without it the active agent is deactivated as on
+   * any swap: a one-way hand-off from a target, whose waiting caller then waits for the new
+   * target. Queued with {@link AgentSession.activate}.
+   */
+  handOff(target, options) {
+    const run = this.activation.then(
+      () => this.activateNow(target, { lock: true, suspendPrevious: options.suspendCaller })
+    );
+    this.activation = run.catch(() => void 0);
+    return run;
+  }
+  /**
+   * Make a waiting caller active again when its hand-off ends (GENC-1737). One whose state is live
+   * resumes without `onActivate`, since it was never deactivated; after a reload it is activated
+   * from its saved state like any other agent. `lock` keeps the flow lock on it: it held it before,
+   * or another caller is still waiting further down.
+   */
+  resume(caller, lock) {
+    const run = this.activation.then(async () => {
+      const index = this.suspended.findIndex((a) => a.name === caller.name);
+      if (index === -1) return this.activateNow(caller, { lock });
+      const [live2] = this.suspended.splice(index, 1);
+      const transition = { previousAgent: this.active, switched: true };
+      recordMetaEvent(this.deps.sessionKey(), "agent.handoff", {
+        from: this.active?.name ?? null,
+        to: live2.name,
+        restored: false
+      });
+      this.active = live2;
+      if (lock && this.flowOwner !== caller.name) {
+        this.flowOwner = caller.name;
+        transition.flowOwnerChangedTo = caller.name;
+      }
+      this.reportTransition(transition);
+      return transition;
+    });
+    this.activation = run.catch(() => void 0);
+    return run;
+  }
+  /**
+   * Deactivate the callers left waiting by hand-offs that ended without a hand-back, newest first,
+   * when no teardown follows to do it (GENC-1737).
+   */
+  async endSuspended() {
+    for (const caller of this.suspended.splice(0).reverse()) {
+      this.handOffData.delete(caller.name);
+      await this.fireDeactivate(caller, "release");
+    }
+  }
   /**
    * Make `agent` active, firing the lifecycle hooks around the swap: outgoing `onDeactivate`
    * first, then incoming `onActivate`. Both are awaited so heavy activation work (a machine
@@ -4982,7 +5074,11 @@ var AgentSession = class {
     this.activation = run.catch(() => void 0);
     return run;
   }
-  async activateNow(agent) {
+  /**
+   * `lock` takes the flow lock whatever kind of agent it is, and `suspendPrevious` leaves the
+   * outgoing agent waiting instead of deactivating it, as a hand-off does (GENC-1737).
+   */
+  async activateNow(agent, { lock = false, suspendPrevious = false } = {}) {
     const previousAgent = this.active;
     const switched = !previousAgent || previousAgent.name !== agent.name;
     const transition = { previousAgent, switched };
@@ -4994,7 +5090,14 @@ var AgentSession = class {
         restored: this.hasRestoredState(agent.name)
       });
     }
-    if (switched && previousAgent) await this.fireDeactivate(previousAgent, "switch");
+    if (switched && previousAgent) {
+      if (suspendPrevious) {
+        this.suspended.push(previousAgent);
+      } else {
+        this.handOffData.delete(previousAgent.name);
+        await this.fireDeactivate(previousAgent, "switch");
+      }
+    }
     if (switched && agent.onActivate) {
       const restored = this.restoredStates[agent.name];
       if (restored !== void 0) delete this.restoredStates[agent.name];
@@ -5011,9 +5114,12 @@ var AgentSession = class {
       }
     }
     const hasLifecycleHooks = !!(agent.onActivate || agent.onDeactivate);
-    if (switched && hasLifecycleHooks && this.flowOwner !== agent.name) {
+    if (switched && (hasLifecycleHooks || lock) && this.flowOwner !== agent.name) {
       this.flowOwner = agent.name;
       transition.flowOwnerChangedTo = agent.name;
+    } else if (switched && !suspendPrevious && this.flowOwner === previousAgent?.name) {
+      this.flowOwner = null;
+      transition.flowOwnerChangedTo = null;
     }
     this.active = agent;
     if (switched) this.reportTransition(transition);
@@ -5031,6 +5137,7 @@ var AgentSession = class {
   async release() {
     const agent = this.active;
     if (!agent) return void 0;
+    this.handOffData.delete(agent.name);
     await this.fireDeactivate(agent, "release");
     this.active = void 0;
     const transition = { previousAgent: agent, switched: true };
@@ -5068,6 +5175,11 @@ var AgentSession = class {
   async dispose() {
     const agent = this.active;
     if (agent) await this.fireDeactivate(agent, "dispose");
+    for (const caller of [...this.suspended].reverse()) {
+      await this.fireDeactivate(caller, "dispose");
+    }
+    this.suspended = [];
+    this.handOffData.clear();
     this.lifecycleAbortController.abort();
     this.active = void 0;
   }
@@ -5107,8 +5219,6 @@ var HARVESTED_SUBAGENT_EVENTS = /* @__PURE__ */ new Set([
   "tool.failed",
   "tool.unresolved"
 ]);
-var REQUEST_CONTINUATION_TOOL = "request_continuation";
-var HANDOFF_TOOL_RESULT_PLACEHOLDER = "Handoff to another specialist \u2014 routing continues on the next turn.";
 
 // src/utils/tool-fold.ts
 var TOOL_FOLD_SYMBOL = Symbol("toolFold");
@@ -6736,6 +6846,16 @@ var SERVICE_WIDE_REFUSALS = /* @__PURE__ */ new Set([
   "ACCESS_DENIED",
   "VENDOR_UNREACHABLE"
 ]);
+var handOffClosingNote = (to) => `[Hand-off]: You handed this request to ${to}, which takes it from here. Tell the user so in one short line. Call no tools, and do not answer the rest of the request.`;
+var HAND_BACK_CLOSING_NOTE = "[Hand-back]: You have finished this request and handed it back. Tell the user so in one short line. Call no tools, and start nothing new.";
+var jsonCopy2 = (value) => {
+  try {
+    const text = JSON.stringify(value);
+    return text === void 0 ? void 0 : JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+};
 var toolResultImages = (result) => {
   if (!result || typeof result !== "object") return void 0;
   const candidate = result.attachments;
@@ -6925,6 +7045,17 @@ var ChatDriver = class _ChatDriver extends EventTarget {
      * doesn't leak forward.
      */
     this.agentReleaseRequested = false;
+    /**
+     * The `agentEnd` activation of each caller waiting in a hand-off, by agent name, with the phase
+     * epoch it was suspended at (GENC-1737). A waiting caller is suspended, not ended, so neither its
+     * `agentEnd` payloads nor its `phaseEnd` ones (to another agent's `endPhase()`) collapse while the
+     * target runs; when it is installed again its entries move to the new activation and, while
+     * their phase had not ended, to the current epoch. A caller restored from a saved session gets
+     * an activation placeholder below zero, which no live activation uses.
+     */
+    this.suspendedActivations = /* @__PURE__ */ new Map();
+    /** The last placeholder handed out for a restored caller; see `suspendedActivations`. */
+    this.restoredSuspensionSeq = 0;
     /**
      * Aborted by `dispose()` on driver teardown (e.g. an agent-config swap).
      * Threaded into every provider call as `ChatRequestOptions.signal`, so a
@@ -6973,8 +7104,8 @@ var ChatDriver = class _ChatDriver extends EventTarget {
      * The stateful-agent contract for this driver: active agent, user pin, flow lock, restored
      * state, and the `onActivate` / `onDeactivate` hooks (§7.1).
      *
-     * **Public because `OrchestratingDriver` reaches through to it.** The orchestrator decorates a
-     * config before installing it (the cross-agent continuation tool), so it cannot route through
+     * **Public because `OrchestratingDriver` reaches through to it.** The orchestrator builds a
+     * config before installing it (the fallback's prompt), so it cannot route through
      * {@link ChatDriver.activateAgent} and must drive the session itself — and one shared session is
      * the point: two would let `getActiveAgent()` disagree between the outer and inner driver.
      * `@internal` rather than private so that reach is legal without six delegating one-liners.
@@ -7381,19 +7512,15 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     this.aiServiceNoticesShown.add(code);
     return false;
   }
-  /**
-   * Whether a sub-agent hit a wall this turn that stops this driver too. A handoff goes on past an
-   * AI-service wall: the next agent may use another vendor, and if it uses this one its own call
-   * meets the wall and says so.
-   */
-  subAgentWallThisTurn(handingOff = false) {
-    return this.providerRefusedThisTurn || this.budgetExhaustedThisTurn || this.aiServiceErrorThisTurn && !handingOff;
+  /** Whether a sub-agent hit a wall this turn that stops this driver too. */
+  subAgentWallThisTurn() {
+    return this.providerRefusedThisTurn || this.budgetExhaustedThisTurn || this.aiServiceErrorThisTurn;
   }
   /**
    * Ends the turn when a sub-agent hit a wall this turn that stops this driver too: the provider
    * refusing the account, the AI service (GENC-1611), or the budget. Checked before each model call,
-   * and again right after a tool batch, before a handoff or the iteration cap can report the turn as
-   * something else.
+   * and again right after a tool batch, before the iteration cap can report the turn as something
+   * else.
    */
   endTurnOnSubAgentWall() {
     if (!this.subAgentWallThisTurn()) return void 0;
@@ -7601,6 +7728,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
   installAgent(config) {
     if (config.name !== this.activeAgentName) {
       this.currentActivation += 1;
+      this.resumeSuspendedActivation(config.name);
       this.resumeRestoredCondensePolicies(config.name);
     }
     this.systemPrompt = config.systemPrompt;
@@ -7802,6 +7930,109 @@ var ChatDriver = class _ChatDriver extends EventTarget {
   getAgentReleaseRequested() {
     return this.agentReleaseRequested;
   }
+  /**
+   * Offer `handOff` and `completeHandOff` to tool handlers, checking each `handOff` with `check`
+   * (GENC-1737). Set by `OrchestratingDriver`, which knows the agents and the hand-off stack and acts
+   * on the request after the call; a bare `ChatDriver` has no other agent to hand to.
+   *
+   * @internal
+   */
+  setHandOffCheck(check) {
+    this.checkHandOff = check;
+  }
+  /** The `handOff` the most recent call accepted, if any (GENC-1737). */
+  getHandOffRequest() {
+    return this.handOffRequested;
+  }
+  /** What `completeHandOff` handed back in the most recent call, if it was called. */
+  getHandOffCompletion() {
+    return this.handOffCompletion;
+  }
+  /**
+   * A handler's `handOff`: refused once this call has handed off or released, or when `data` is
+   * not JSON, and otherwise checked by the orchestrator. `data` is kept as a JSON copy, since it is
+   * saved with the session and the handler may change its own object afterwards.
+   */
+  requestHandOff(request) {
+    if (this.handOffRequested) return { ok: false, reason: "already-requested" };
+    if (this.agentReleaseRequested) return { ok: false, reason: "released" };
+    let data;
+    if (request?.data !== void 0) {
+      data = jsonCopy2(request.data);
+      if (data === void 0) return { ok: false, reason: "not-json" };
+    }
+    const accepted = {
+      to: request.to,
+      message: String(request.message ?? ""),
+      ...data !== void 0 && { data },
+      ...request.returnTo === false && { returnTo: false }
+    };
+    const result = this.checkHandOff(accepted, this.activeAgentName);
+    if (result.ok) this.handOffRequested = accepted;
+    return result;
+  }
+  /**
+   * The note of the closing call a hand-off asks for (GENC-1737), or `undefined` when none: once a
+   * handler's `handOff` is accepted, or `completeHandOff` is called, the rest of that batch runs,
+   * then one model call with no tools, so the agent can say so but not carry on, which a model told
+   * so in a tool result does anyway. Then the turn ends.
+   */
+  closingCallNote() {
+    if (this.handOffRequested) return handOffClosingNote(this.handOffRequested.to);
+    return this.handOffCompletion ? HAND_BACK_CLOSING_NOTE : void 0;
+  }
+  /**
+   * Suspend the active agent's activation for a hand-off it made (GENC-1737): installing the target
+   * advances the `agentEnd` clock as any swap does, but this caller's payloads stay live.
+   */
+  suspendActivation(agentName) {
+    if (agentName === this.activeAgentName) {
+      this.suspendedActivations.set(agentName, {
+        activation: this.currentActivation,
+        phaseEpoch: this.currentPhaseEpoch
+      });
+    }
+  }
+  /**
+   * Suspend restored callers before their condense policies are restored, so entries still live
+   * at save time stay live instead of waiting for "the next activation", which is the target's.
+   */
+  suspendRestoredActivations(agentNames) {
+    for (const name of agentNames) {
+      this.restoredSuspensionSeq -= 1;
+      this.suspendedActivations.set(name, {
+        activation: this.restoredSuspensionSeq,
+        phaseEpoch: this.currentPhaseEpoch
+      });
+    }
+  }
+  /** End every suspension: the hand-offs were unwound, so their callers' activations are over. */
+  endSuspendedActivations() {
+    this.suspendedActivations.clear();
+  }
+  /**
+   * A caller installed again takes its suspended entries into the activation it resumes in, and
+   * the ones whose phase had not ended into the current phase epoch.
+   */
+  resumeSuspendedActivation(agentName) {
+    const suspended = this.suspendedActivations.get(agentName);
+    if (suspended === void 0) return;
+    this.suspendedActivations.delete(agentName);
+    for (const entry of this.condensePolicies.values()) {
+      if (entry.activation !== suspended.activation) continue;
+      entry.activation = this.currentActivation;
+      if (entry.phaseEpoch >= suspended.phaseEpoch) entry.phaseEpoch = this.currentPhaseEpoch;
+    }
+  }
+  /**
+   * The suspended activations, each with the phase epoch it was suspended at, for the `agentEnd`
+   * and `phaseEnd` checks and for persistence.
+   */
+  suspendedClocks() {
+    return new Map(
+      [...this.suspendedActivations.values()].map((s) => [s.activation, s.phaseEpoch])
+    );
+  }
   /**
    * Act on a `releaseAgent` call from a tool handler: fire `onDeactivate` and drop the flow lock,
    * so the next turn starts clean and the persister does not serialize a flow that is over.
@@ -7940,7 +8171,12 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    * @beta
    */
   getCondensePoliciesForPersistence(messages) {
-    return snapshotCondensePolicies(this.condensePolicies, this.condenseClocks(), messages);
+    return snapshotCondensePolicies(
+      this.condensePolicies,
+      this.condenseClocks(),
+      messages,
+      this.suspendedClocks()
+    );
   }
   /**
    * Re-register policies saved by {@link ChatDriver.getCondensePoliciesForPersistence} against
@@ -7989,9 +8225,13 @@ var ChatDriver = class _ChatDriver extends EventTarget {
       const entry = parsePersistedCondensePolicy(raw);
       if (!entry || !present.has(entry.toolCallId)) continue;
       if (this.condensePolicies.has(entry.toolCallId)) continue;
-      this.condensePolicies.set(entry.toolCallId, rebaseRestoredCondensePolicy(entry, clocks));
+      const registered = rebaseRestoredCondensePolicy(entry, clocks);
+      this.condensePolicies.set(entry.toolCallId, registered);
       restored += 1;
-      if (entry.elapsed.activations === 0 && entry.agent !== this.activeAgentName) {
+      const suspended = entry.elapsed.activations === 0 && entry.agent !== void 0 ? this.suspendedActivations.get(entry.agent) : void 0;
+      if (suspended !== void 0) {
+        registered.activation = suspended.activation;
+      } else if (entry.elapsed.activations === 0 && entry.agent !== this.activeAgentName) {
         this.condenseAwaitingReactivation.add(entry.toolCallId);
         awaitingReactivation += 1;
       }
@@ -8348,6 +8588,8 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     this.subAgentCompletion = void 0;
     this.subAgentFailure = void 0;
     this.agentReleaseRequested = false;
+    this.handOffRequested = void 0;
+    this.handOffCompletion = void 0;
     this.budgetExhaustedThisTurn = false;
     this.budgetWallDetail = void 0;
     this.budgetWallViaSubAgent = false;
@@ -8481,6 +8723,12 @@ var ChatDriver = class _ChatDriver extends EventTarget {
         this.currentActivation += 1;
       },
       releaseAgent: () => {
+        if (this.handOffRequested) {
+          logger2.warn(
+            `ChatDriver(${this.activeAgentName ?? "unknown"}): releaseAgent called after handOff \u2014 ignoring; the hand-off ends this agent's turn`
+          );
+          return;
+        }
         if (this.agentReleaseRequested) {
           logger2.warn(
             `ChatDriver(${this.activeAgentName ?? "unknown"}): releaseAgent called more than once \u2014 ignoring`
@@ -8490,6 +8738,34 @@ var ChatDriver = class _ChatDriver extends EventTarget {
         this.agentReleaseRequested = true;
         this.currentActivation += 1;
       },
+      ...this.checkHandOff && {
+        handOff: (request) => this.requestHandOff(request),
+        // A copy, so a handler cannot change what is saved.
+        handOffData: () => jsonCopy2(this.agentSession.getHandOffData(this.activeAgentName ?? "")),
+        completeHandOff: (completion) => {
+          if (this.agentReleaseRequested || this.handOffRequested) {
+            logger2.warn(
+              `ChatDriver(${this.activeAgentName ?? "unknown"}): completeHandOff called after a release or a hand-off \u2014 ignoring`
+            );
+            return;
+          }
+          let data;
+          if (completion?.data !== void 0) {
+            data = jsonCopy2(completion.data);
+            if (data === void 0) {
+              logger2.warn(
+                `ChatDriver(${this.activeAgentName ?? "unknown"}): completeHandOff data cannot be saved as JSON \u2014 handing back without it`
+              );
+            }
+          }
+          this.handOffCompletion = {
+            message: String(completion?.message ?? ""),
+            ...data !== void 0 && { data }
+          };
+          this.agentReleaseRequested = true;
+          this.currentActivation += 1;
+        }
+      },
       endPhase: () => {
         this.currentPhaseEpoch += 1;
       },
@@ -8692,6 +8968,9 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     this.beginTurn();
     this.subAgentCompletion = void 0;
     this.subAgentFailure = void 0;
+    this.agentReleaseRequested = false;
+    this.handOffRequested = void 0;
+    this.handOffCompletion = void 0;
     this.budgetExhaustedThisTurn = false;
     this.budgetWallDetail = void 0;
     this.budgetWallViaSubAgent = false;
@@ -8759,7 +9038,8 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     let firstLlmCall = !!currentInput;
     let pinnedThinkingPolicy;
     let thinkingPolicyPinned = false;
-    while (iterations < this.maxToolIterations) {
+    let closingCallMade = false;
+    while (iterations < this.maxToolIterations || this.closingCallNote() && !closingCallMade) {
       iterations += 1;
       this.modelCallSeq += 1;
       if (this.turnController.signal.aborted) {
@@ -8767,6 +9047,8 @@ var ChatDriver = class _ChatDriver extends EventTarget {
       }
       const wall = this.endTurnOnSubAgentWall();
       if (wall) return wall;
+      if (closingCallMade) return turnDone();
+      const closing = this.closingCallNote();
       const promptCtx = {
         agentName: this.activeAgentName ?? "",
         history: this.history,
@@ -8808,13 +9090,17 @@ ${EMPTY_RESPONSE_NUDGE}` : "";
       const firstCallNote = tailNote && iterations === 1 ? `
 
 ${tailNote}` : "";
-      const frameworkSystemSuffix = `${foldSuffix}${firstCallNote}${retryNudge}`;
+      const closingNote = closing ? `
+
+${closing}` : "";
+      const frameworkSystemSuffix = `${foldSuffix}${firstCallNote}${closingNote}${retryNudge}`;
       const primer = normalizeForProvider([
         ...this.primerHistory ?? [],
         ...transientPrimer ?? []
       ]);
       const baseHistory = firstLlmCall ? this.history.slice(0, -1) : this.history;
       firstLlmCall = false;
+      const suspended = this.suspendedClocks();
       const condensedHistory = applyCondensation(
         [...baseHistory],
         this.condensePolicies,
@@ -8823,10 +9109,11 @@ ${tailNote}` : "";
           turn: this.turnSeq,
           // A call's activation has ended once a later activation is current — a
           // swap or release/complete both advance the counter.
-          activationEnded: (activation) => activation < this.currentActivation,
+          // A caller waiting in a hand-off is suspended, not ended (GENC-1737).
+          activationEnded: (activation) => activation < this.currentActivation && !suspended.has(activation),
           // A call's phase has ended once the app declared a later phase epoch
-          // current via `endPhase()`.
-          phaseEnded: (phaseEpoch) => phaseEpoch < this.currentPhaseEpoch,
+          // current via `endPhase()`; a waiting caller's, only by one before it waited.
+          phaseEnded: (phaseEpoch, activation) => phaseEpoch < (suspended.get(activation) ?? this.currentPhaseEpoch),
           batchCalls: this.condenseBatchCalls
         },
         (detail) => recordMetaEvent(this.sessionKey, "context.condensed", detail)
@@ -8866,7 +9153,7 @@ ${tailNote}` : "";
       const tailContext = tailBody ? `<system-reminder>
 ${tailBody}
 </system-reminder>` : void 0;
-      const effectiveToolChoice = resolvedToolChoice ?? (this.isSubAgent ? "required" : void 0);
+      const effectiveToolChoice = closing ? "none" : resolvedToolChoice ?? (this.isSubAgent ? "required" : void 0);
       const turnSnapshot = this.turnRecorder.record({
         agentName: this.activeAgentName,
         agentLabel: this.activeAgentLabel,
@@ -8938,6 +9225,7 @@ ${tailBody}
         });
         return this.endTurnWithFailure(TURN_FAILURE_EXITS.contextGuard);
       }
+      if (closing) closingCallMade = true;
       let response;
       try {
         response = await activeProvider.chat(historyForCall, userInputForCall, options);
@@ -9071,6 +9359,10 @@ ${tailBody}
       }
       turnSnapshot.usage = messageUsage(response);
       if (response.model !== void 0) turnSnapshot.model = response.model;
+      if (closing) {
+        if (response.toolCalls?.length) response = { ...response, toolCalls: void 0 };
+        if (!response.content?.trim()) return turnDone();
+      }
       const isThinkingStep = response.content && response.toolCalls?.length;
       const isEmptyResponse = !response.content?.trim() && !response.toolCalls?.length;
       const isRefusal = response.responseMeta?.finishReason === "refusal";
@@ -9148,17 +9440,11 @@ ${tailBody}
       emptyResponseAttempts = 0;
       malformedAttempts = 0;
       setupTransportAttempts = 0;
+      if (closing) return turnDone();
       if (!response.toolCalls?.length) {
         break;
       }
-      const [toolCalls, systemCalls] = response.toolCalls.reduce(
-        (acc, tc) => {
-          if (tc.name === REQUEST_CONTINUATION_TOOL) acc[1].push(tc);
-          else acc[0].push(tc);
-          return acc;
-        },
-        [[], []]
-      );
+      const toolCalls = response.toolCalls;
       const executedById = /* @__PURE__ */ new Map();
       const unknownToolIds = /* @__PURE__ */ new Set();
       const staleToolIds = /* @__PURE__ */ new Set();
@@ -9336,28 +9622,20 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
       }
       const foldPath = this.folds.activeNames();
       for (const tc of response.toolCalls) {
-        if (tc.name === REQUEST_CONTINUATION_TOOL) {
+        const r = executedById.get(tc.id);
+        if (r) {
           this.appendToHistory({
             role: "tool",
             content: "",
-            toolResult: { toolCallId: tc.id, content: HANDOFF_TOOL_RESULT_PLACEHOLDER }
+            toolResult: {
+              toolCallId: r.toolCallId,
+              content: r.content,
+              // Images DO persist, unlike the sub-agent trace above: they are the payload
+              // the model must see on every replay of this turn, not a one-off UI artefact.
+              // `condenseWhen` is what sheds them once they are spent — see condense-history.
+              ...r.attachments ? { attachments: r.attachments } : {}
+            }
           });
-        } else {
-          const r = executedById.get(tc.id);
-          if (r) {
-            this.appendToHistory({
-              role: "tool",
-              content: "",
-              toolResult: {
-                toolCallId: r.toolCallId,
-                content: r.content,
-                // Images DO persist, unlike the sub-agent trace above: they are the payload
-                // the model must see on every replay of this turn, not a one-off UI artefact.
-                // `condenseWhen` is what sheds them once they are spent — see condense-history.
-                ...r.attachments ? { attachments: r.attachments } : {}
-              }
-            });
-          }
         }
       }
       let tcMsgIdx = -1;
@@ -9421,8 +9699,7 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
         });
         return this.endTurnWithFailure(TURN_FAILURE_EXITS.unknownToolLimit);
       }
-      const firstContinuation = systemCalls[0];
-      if (!this.subAgentCompletion && this.subAgentWallThisTurn(!!firstContinuation)) {
+      if (!this.subAgentCompletion && this.subAgentWallThisTurn()) {
         if (this.turnController.signal.aborted) return this.completeAbortedTurn();
         const wallAfterBatch = this.endTurnOnSubAgentWall();
         if (wallAfterBatch) return wallAfterBatch;
@@ -9431,10 +9708,6 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
         this.noticeAIServiceRefusal(this.aiServiceWall.code);
         this.flushAIServiceNotices();
       }
-      if (firstContinuation) {
-        const { summary, remaining_task: remainingTask } = firstContinuation.args;
-        return { reason: "agent-handoff", summary, remainingTask };
-      }
       if (this.subAgentCompletion) {
         return turnDone();
       }
@@ -9510,6 +9783,9 @@ var AI_DRIVER_EVENT_TYPES = Object.keys({
   "agent-changed": true,
   "agent-released": true,
   "flow-owner-changed": true,
+  "handoff-started": true,
+  "handoff-returned": true,
+  "handoff-unwound": true,
   "orchestrating-start": true,
   "orchestrating-stop": true
 });
@@ -9590,6 +9866,24 @@ var BaseDriverDecorator = class _BaseDriverDecorator extends EventTarget {
   restoreCondensePolicies(entries) {
     return this.inner.restoreCondensePolicies?.(entries) ?? { restored: 0, awaitingReactivation: 0 };
   }
+  getHandOffStack() {
+    return this.inner.getHandOffStack?.() ?? [];
+  }
+  restoreHandOffStack(saved, savedStates, interrupted) {
+    return this.inner.restoreHandOffStack?.(saved, savedStates, interrupted) ?? {};
+  }
+  unwindHandOffs(kind) {
+    return this.inner.unwindHandOffs?.(kind) ?? Promise.resolve();
+  }
+  serializeWaitingCallers() {
+    return this.inner.serializeWaitingCallers?.() ?? {};
+  }
+  getHandOffData() {
+    return this.inner.getHandOffData?.() ?? {};
+  }
+  restoreHandOffData(saved, interrupted) {
+    this.inner.restoreHandOffData?.(saved, interrupted);
+  }
   getActiveAgent() {
     return this.inner.getActiveAgent();
   }
@@ -9698,36 +9992,64 @@ var BaseDriverDecorator = class _BaseDriverDecorator extends EventTarget {
   }
 };
 
+// src/components/orchestrating-driver/hand-off.ts
+var OUTCOME_KINDS = [
+  "completed",
+  "released",
+  "cleared",
+  "agent-removed",
+  "state-lost"
+];
+function handOffNote(caller) {
+  return `[Hand-off]: ${caller} handed this request to you. Its brief is the message above. Work on it as you would on a request from the user.`;
+}
+function handBackNote(frame, outcome) {
+  const how = {
+    completed: `${frame.target} has finished the request you handed it.`,
+    released: `${frame.target} has finished the request you handed it, without a summary. Its last reply is above.`,
+    cleared: "The hand-off was cleared.",
+    "agent-removed": `${frame.target} is no longer available, so the request you handed it was not finished.`,
+    "state-lost": `The hand-off to ${frame.target} could not be resumed.`
+  };
+  const summary = outcome.kind === "completed" && outcome.message ? " Its summary is the message above." : "";
+  return `[Hand-back]: ${how[outcome.kind]}${summary} Carry on with the user from here.`;
+}
+var frameCopy = (frame) => structuredClone(frame);
+var isOutcome = (value) => {
+  const o = value;
+  return !!o && typeof o === "object" && OUTCOME_KINDS.includes(o.kind) && (o.message === void 0 || typeof o.message === "string");
+};
+function parseHandOffFrames(saved) {
+  if (!Array.isArray(saved)) return [];
+  return saved.filter((value) => {
+    const f = value;
+    return !!f && typeof f === "object" && typeof f.id === "string" && typeof f.caller === "string" && typeof f.target === "string" && typeof f.returnTo === "boolean" && typeof f.message === "string" && typeof f.startedAt === "string" && (f.outcome === void 0 || isOutcome(f.outcome));
+  });
+}
+
 // src/components/orchestrating-driver/orchestrating-driver.ts
 var DEFAULT_MAX_HANDOFFS = 3;
+var DEFAULT_MAX_HAND_OFF_DEPTH = 1;
 var DEFAULT_CLASSIFIER_HISTORY_LENGTH = 4;
 var DEFAULT_CLASSIFIER_RETRIES = 2;
 var CLASSIFIER_MESSAGE_CHARS = 600;
 var CLASSIFIER_TRANSCRIPT_CHARS = 3e3;
-var REQUEST_CONTINUATION_DEFINITION = {
-  name: REQUEST_CONTINUATION_TOOL,
-  description: "Call this when you have completed your part of the task but fulfilling the user's full request requires capabilities outside your domain. Do not call this if you can complete the request yourself. Pass a plain-language description of what still needs to be done \u2014 another specialist will be selected automatically.",
-  parameters: {
-    type: "object",
-    required: ["summary", "remaining_task"],
-    properties: {
-      summary: {
-        type: "string",
-        description: "What you found or did \u2014 passed as context to the next specialist."
-      },
-      remaining_task: {
-        type: "string",
-        description: "What still needs to be done, in plain language. Used to route to the right specialist."
-      }
-    }
-  }
-};
 function isSpecialist(agent) {
   return !agent.fallback;
 }
 function isFallback(agent) {
   return agent.fallback === true;
 }
+function isStateful(agent) {
+  return !!(agent.onActivate || agent.onDeactivate);
+}
+async function callHandOffHook(agent, hook, run) {
+  try {
+    await run();
+  } catch (e) {
+    logger2.warn(`OrchestratingDriver: ${hook}("${agent}") threw:`, e);
+  }
+}
 function normalizeContextReserve(input) {
   if (input == null) return void 0;
   const positive = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
@@ -9760,37 +10082,40 @@ Politely let the user know what you can help with and invite them to rephrase th
 
 ${UNROUTABLE_INSTRUCTION}`;
 }
-function handoffTailNote(agent, remainingTask) {
-  if (isFallback(agent)) {
-    return "[Hand-off]: no specialist here can take on what remains. Reply to the user now, as the routing note says.";
-  }
-  const work = remainingTask?.trim();
-  return work ? `[Hand-off]: the previous agent passed the rest of this request to you. What remains: ${work}` : "[Hand-off]: the previous agent passed the rest of this request to you without saying what remains. Carry on with the user's request above.";
-}
 var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator {
   constructor(providerRegistry, agents, options = {}) {
     super(_OrchestratingDriver.createInner(providerRegistry, agents, options));
     this.providerRegistry = providerRegistry;
     this.agents = agents;
     /**
-     * Set by `cancel()` for the duration of a `sendMessage` run. Breaks the
-     * handoff loop so we don't classify or start another agent turn after the
-     * user stops. Reset at the start of each `sendMessage`.
+     * Set by `cancel()` for the duration of a run. Stops it before the next agent
+     * runs — a hand-off's target or a hand-back's caller — so nothing more is asked
+     * of a provider after the user stops. Reset at the start of each run.
      */
     this.cancelled = false;
     /**
      * Whether the CURRENT turn's user message has reached the inner driver's
      * history. False through the pre-first-turn classify (where the only echo of
      * the message is an optimistic `history-updated` dispatch), true from the
-     * moment `chatDriver.sendMessage` is entered — including through every later
-     * handoff classify. Read by the budget-wall catch in `sendMessage` to decide
+     * moment `chatDriver.sendMessage` is entered. Read by the budget-wall catch in
+     * `sendMessage` to decide
      * whether `reportBudgetExhausted` must append the message itself: appending
      * it when already appended duplicated it; not appending it when unappended
      * made it vanish. Reset at the top of each `runOrchestratedTurn`.
      */
     this.userMessageAppended = false;
+    /**
+     * The hand-offs in progress, oldest first (GENC-1737). The top frame's target is the active agent
+     * and holds the flow lock; each caller waits, suspended, for the target above it. Saved with the
+     * session through {@link OrchestratingDriver.getHandOffStack}.
+     */
+    this.handOffStack = [];
+    /** Hand-offs and hand-backs this user turn, against `maxHandoffs`. */
+    this.handOffsThisTurn = 0;
     this.sessionKey = options.sessionKey ?? "";
     this.maxHandoffs = options.maxHandoffs ?? DEFAULT_MAX_HANDOFFS;
+    this.maxHandOffDepth = options.maxHandOffDepth ?? DEFAULT_MAX_HAND_OFF_DEPTH;
+    this.chatDriver.setHandOffCheck((request, caller) => this.checkHandOff(request, caller));
     this.classifierHistoryLength = options.classifierHistoryLength ?? DEFAULT_CLASSIFIER_HISTORY_LENGTH;
     this.classifierRetries = options.classifierRetries ?? DEFAULT_CLASSIFIER_RETRIES;
     this.specialists = agents.filter(isSpecialist).filter((a) => !a.excludeFromClassifier);
@@ -9843,7 +10168,7 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
       activityBus: options.activityBus,
       budgetExhaustedMessage: options.budgetExhaustedMessage,
       aiServiceErrorMessages: options.aiServiceErrorMessages,
-      // A release ends this driver's handoff loop, so it acts on the flag itself; see the option.
+      // A release can hand back to a waiting caller, so this driver acts on the flag itself.
       deferAgentRelease: true
     });
   }
@@ -9883,6 +10208,8 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
   async runOrchestratedTurn(input, attachments, options, delegated) {
     this.cancelled = false;
     this.userMessageAppended = false;
+    this.handOffsThisTurn = 0;
+    if (this.pendingHandBack?.resumed) this.pendingHandBack = void 0;
     const history = this.chatDriver.getHistory();
     this.dispatchEvent(
       new CustomEvent("history-updated", {
@@ -9900,66 +10227,16 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
     } else {
       routed = await this.classify(routingInput, history, this.activeAgent);
     }
-    let currentAgent = routed.agent;
-    let isHandoff = false;
-    let handoffs = 0;
-    let handoffSummary = "";
-    let remainingTask = "";
-    const attempted = [];
     let lastResult;
-    while (true) {
-      if (this.cancelled) break;
-      await this.installAgent(currentAgent, pin);
-      if (this.cancelled) break;
-      let result;
-      if (isHandoff) {
-        const contextPrimer = handoffSummary ? [{ role: "user", content: `[Context from previous agent]: ${handoffSummary}` }] : [];
-        if (isFallback(currentAgent)) {
-          const work = remainingTask?.trim() || handoffSummary?.trim();
-          contextPrimer.push({
-            role: "user",
-            content: (work ? `[Routing note]: no specialist is available for the remaining work: ${work}
-` : "[Routing note]: no specialist is available for the work that remains.\n") + "Tell the user plainly what was established, that this part falls outside what any specialist here can do, and what they could do next. Do not claim you will do it yourself, and do not return an empty response."
-          });
-        }
-        result = await this.chatDriver.continueFromHistory(contextPrimer, {
-          tailNote: handoffTailNote(currentAgent, remainingTask)
-        });
-      } else {
+    if (!this.cancelled) {
+      await this.endOrphanedHandOffs(routed.agent);
+      await this.installAgent(routed.agent);
+      if (!this.cancelled) {
         this.userMessageAppended = true;
-        result = await this.chatDriver.sendMessage(input, attachments, options);
-      }
-      lastResult = result;
-      if (this.chatDriver.getAgentReleaseRequested()) {
-        await this.releaseActiveAgent();
-        break;
-      }
-      if (result.reason !== "agent-handoff" || isFallback(currentAgent) || pinned) {
-        break;
-      }
-      if (this.cancelled) break;
-      handoffs += 1;
-      if (handoffs > this.maxHandoffs) {
-        this.appendInlineMessage(
-          `I wasn't able to fully complete your request \u2014 the task required more hand-offs between specialists than allowed. Please try breaking your request into smaller steps.`
+        lastResult = await this.carryOn(
+          await this.chatDriver.sendMessage(input, attachments, options)
         );
-        break;
       }
-      handoffSummary = result.summary;
-      remainingTask = result.remainingTask;
-      isHandoff = true;
-      if (isSpecialist(currentAgent) && !attempted.includes(currentAgent.name)) {
-        attempted.push(currentAgent.name);
-      }
-      const updatedHistory = this.chatDriver.getHistory();
-      this.dispatchEvent(new CustomEvent("orchestrating-start"));
-      routed = await this.classify(
-        remainingTask?.trim() || routingInput,
-        updatedHistory,
-        void 0,
-        attempted
-      );
-      currentAgent = routed.agent;
     }
     if (this.cancelled && !this.userMessageAppended) {
       this.chatDriver.reportStoppedBeforeTurn({
@@ -9969,7 +10246,74 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
         ...delegated
       });
     }
-    return lastResult?.reason === "done" ? lastResult : { reason: "done" };
+    return lastResult ?? { reason: "done" };
+  }
+  /**
+   * Act on what the agent call that just ended asked for, and run the next agent in the same user
+   * turn while there is one (GENC-1737): a `handOff` runs its target with the brief, and a target
+   * that releases hands back to its caller. Returns the last call's result.
+   *
+   * A failed call ends the turn there, as a Stop does: what it asked for still happens, and the
+   * next agent runs on the next message. Running it now would meet the same wall (a budget, a
+   * refused account, a full context window), or build on a reply that never came.
+   */
+  async carryOn(result) {
+    let last = result;
+    let tailNote = await this.afterAgentCall();
+    while (tailNote !== void 0 && !this.cancelled && !last.failureReason) {
+      last = await this.chatDriver.continueFromHistory(void 0, { tailNote });
+      tailNote = await this.afterAgentCall();
+    }
+    return last;
+  }
+  /**
+   * After one agent call: start the hand-off it asked for, or release it and, when it was a
+   * hand-off's target, hand back. Returns the tail note for the agent to run next, or `undefined`
+   * when the turn ends here.
+   *
+   * A plain target hands back when its call ends, released or not, as a plain agent is done once
+   * it has answered. A stateful one holds the hand-off until it releases, as it holds its flow.
+   */
+  async afterAgentCall() {
+    const request = this.chatDriver.getHandOffRequest();
+    if (request) return this.startHandOff(request);
+    const active = this.agentSession.getActive();
+    if (!active) return void 0;
+    const frame = this.topFrameFor(active.name);
+    const released = this.chatDriver.getAgentReleaseRequested();
+    if (!released && !(frame && !isStateful(active))) {
+      if (!isStateful(active)) this.endPlainTurn(active);
+      return void 0;
+    }
+    if (!frame) {
+      await this.releaseActiveAgent();
+      return void 0;
+    }
+    frame.outcome = this.outcomeOf(frame);
+    await this.releaseActiveAgent();
+    return this.handBack(frame, frame.outcome);
+  }
+  /** How the target of `frame` finished: with `completeHandOff`, or a release and its last reply. */
+  outcomeOf(frame) {
+    const completion = this.chatDriver.getHandOffCompletion();
+    if (completion) {
+      return {
+        kind: "completed",
+        message: completion.message,
+        ...completion.data !== void 0 && { data: completion.data }
+      };
+    }
+    const finalReply = this.lastReply(frame);
+    return { kind: "released", ...finalReply ? { message: finalReply } : {} };
+  }
+  /**
+   * A plain agent is done once it has answered (GENC-1737): the data a one-way hand-off gave it ends
+   * with its turn, and so does a flow lock no hand-off holds, such as one a restore left on a
+   * target whose hand-off it could not resume.
+   */
+  endPlainTurn(agent) {
+    this.agentSession.setHandOffData(agent.name, void 0);
+    if (this.agentSession.getFlowOwner() === agent.name) this.agentSession.dropFlowLock();
   }
   /** {@inheritDoc AiDriver.canRestoreFlowOwner} */
   canRestoreFlowOwner(agentName) {
@@ -9993,15 +10337,33 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
    * undecorated.
    */
   async resumeRestoredFlow(resumeNote) {
+    if (this.pendingHandBack) return this.resumeHandBack(resumeNote);
     const owner = this.agentSession.getFlowOwner();
     const agent = owner ? this.agents.find((a) => a.name === owner) : void 0;
     if (!agent) return void 0;
     this.cancelled = false;
+    this.handOffsThisTurn = 0;
     await this.installAgent(agent);
     if (!resumeNote || agent.resumeOnRestore === false || this.cancelled) return void 0;
-    const result = await this.chatDriver.continueFromHistory(void 0, { tailNote: resumeNote });
-    await this.releaseIfRequested();
-    return result;
+    return this.carryOn(
+      await this.chatDriver.continueFromHistory(void 0, { tailNote: resumeNote })
+    );
+  }
+  /**
+   * The hand-back a restore found due (GENC-1737). The first call, inside the host's restore gate,
+   * makes the caller active again and tells it the outcome; the call with the note runs its turn.
+   */
+  async resumeHandBack(note) {
+    const pending = this.pendingHandBack;
+    this.cancelled = false;
+    if (!pending.resumed) {
+      pending.resumed = true;
+      await this.handBack(pending.frame, pending.frame.outcome);
+    }
+    if (!note || this.cancelled) return void 0;
+    this.pendingHandBack = void 0;
+    this.handOffsThisTurn = 0;
+    return this.carryOn(await this.chatDriver.continueFromHistory(void 0, { tailNote: note }));
   }
   /**
    * A continuation outside a routed turn — a decorator carrying the agent on, say — can finish the
@@ -10009,15 +10371,9 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
    * (GENC-1660), only `sendMessage` checked, and a flow finished by a continuation stayed locked.
    */
   async continueFromHistory(transientPrimer, options) {
-    const result = await this.chatDriver.continueFromHistory(transientPrimer, options);
-    await this.releaseIfRequested();
-    return result;
-  }
-  /** Release the flow if the turn that just ended asked to, and an agent is still active to release. */
-  async releaseIfRequested() {
-    if (this.chatDriver.getAgentReleaseRequested() && this.agentSession.getActive()) {
-      await this.releaseActiveAgent();
-    }
+    this.cancelled = false;
+    this.handOffsThisTurn = 0;
+    return this.carryOn(await this.chatDriver.continueFromHistory(transientPrimer, options));
   }
   /**
    * {@inheritDoc AiDriver.getContextReserve}
@@ -10045,25 +10401,18 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
     }
     return winner ? { ...winner, agentName, basis: "reachable-max" } : void 0;
   }
+  /** Make `agent` active through the session, firing its hooks, and install it. */
+  async installAgent(agent) {
+    const { previousAgent } = await this.agentSession.activate(agent);
+    this.applyAgent(agent, previousAgent?.name);
+  }
   /**
-   * `pin` stands in for the user-pin when given, as for
-   * {@link OrchestratingDriver.resolvePinnedAgent}.
+   * Install an agent the session has already made active on the inner driver: the transcript's
+   * divider when another agent spoke before it, and its own view of the history. What is left here
+   * is this driver's own job, the transcript; the session owns the lifecycle.
    */
-  async installAgent(agent, pin) {
-    const { previousAgent } = await this.agentSession.activate(agent);
-    const isTerminal = isFallback(agent) || (pin === void 0 ? this.agentSession.getPinned() : pin) !== null || this.agentSession.getFlowOwner() !== null || !!(agent.onActivate || agent.onDeactivate);
-    let agentToApply = agent;
-    if (!isTerminal) {
-      const declaredTools = agent.toolDefinitions;
-      agentToApply = {
-        ...agent,
-        toolDefinitions: typeof declaredTools === "function" ? async (ctx) => [
-          ...await declaredTools(ctx),
-          REQUEST_CONTINUATION_DEFINITION
-        ] : [...declaredTools ?? [], REQUEST_CONTINUATION_DEFINITION]
-      };
-    }
-    if (previousAgent && previousAgent.name !== agent.name) {
+  applyAgent(agent, previousName) {
+    if (previousName && previousName !== agent.name) {
       const rawHistory = this.chatDriver.getHistory();
       this.chatDriver.loadHistory([
         ...rawHistory,
@@ -10071,7 +10420,7 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
       ]);
     }
     this.chatDriver.setProviderHistoryTransform((h) => transformHistoryForAgent(h, agent.name));
-    this.chatDriver.installAgent(agentToApply);
+    this.chatDriver.installAgent(agent);
     this.dispatchEvent(new CustomEvent("orchestrating-stop"));
   }
   /**
@@ -10088,10 +10437,250 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
   async releaseActiveAgent() {
     await this.agentSession.release();
   }
+  /** The agent named `name` as this driver installs it: the fallback with its prompt built. */
+  agentNamed(name) {
+    if (this.fallback?.name === name) return this.fallback;
+    return this.agents.find((a) => a.name === name);
+  }
+  /**
+   * End the hand-offs when a turn runs an agent other than the top target (GENC-1737): the lock
+   * that kept turns on the target was taken away, by a host clearing `flowOwnerAgentName` say,
+   * and its caller would otherwise wait for good.
+   */
+  async endOrphanedHandOffs(agent) {
+    const top = this.handOffStack[this.handOffStack.length - 1];
+    if (!top || top.outcome || top.target === agent.name) return;
+    await this.unwindHandOffs("cleared");
+    await this.agentSession.endSuspended();
+  }
+  /**
+   * Check a handler's `handOff` when it is made (GENC-1737), so a refusal reaches its model. Checked
+   * against the agents and the stack as they are now; the hand-off itself starts after the call.
+   */
+  checkHandOff(request, caller) {
+    const target = this.agentNamed(request.to);
+    if (!target) return { ok: false, reason: "unknown-agent" };
+    const allowed = this.agents.find((a) => a.name === caller)?.handOffTargets;
+    if (allowed && !allowed.includes(target.name)) return { ok: false, reason: "not-allowed" };
+    if (target.name === caller || this.handOffStack.some((f) => f.caller === target.name || f.target === target.name)) {
+      return { ok: false, reason: "re-entry" };
+    }
+    if (request.returnTo !== false && this.handOffStack.length >= this.maxHandOffDepth) {
+      return { ok: false, reason: "depth" };
+    }
+    if (this.handOffsThisTurn >= this.maxHandoffs) return { ok: false, reason: "limit" };
+    return { ok: true };
+  }
+  /**
+   * Start the hand-off the agent call just made, and return the target's tail note (GENC-1737).
+   *
+   * - `returnTo` (the default): push a frame. The caller waits without being deactivated, its
+   *   `agentEnd` payloads suspended, and the target takes the flow lock.
+   * - One-way from a hand-off's target: that frame's caller now waits for the new target instead.
+   * - One-way with nobody waiting: a plain switch, the caller deactivated as on any swap.
+   *
+   * Either way the brief is recorded as a message the caller sent on the user's behalf.
+   */
+  async startHandOff(request) {
+    const caller = this.agentSession.getActive();
+    const target = this.agentNamed(request.to);
+    if (!caller || !target) return void 0;
+    this.handOffsThisTurn += 1;
+    const frame = {
+      id: crypto.randomUUID(),
+      caller: caller.name,
+      target: target.name,
+      returnTo: request.returnTo !== false,
+      message: request.message,
+      ...request.data !== void 0 && { data: request.data },
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const top = this.handOffStack[this.handOffStack.length - 1];
+    if (frame.returnTo) {
+      this.handOffStack.push(frame);
+      await callHandOffHook(
+        caller.name,
+        "onHandOffStart",
+        () => caller.onHandOffStart?.(frameCopy(frame))
+      );
+      this.chatDriver.suspendActivation(caller.name);
+      await this.agentSession.handOff(target, { suspendCaller: true });
+    } else if (top?.target === caller.name) {
+      top.target = target.name;
+      await this.agentSession.handOff(target, { suspendCaller: false });
+    } else {
+      await this.agentSession.activate(target);
+    }
+    this.applyAgent(this.agentSession.getActive() ?? target, caller.name);
+    this.agentSession.setHandOffData(target.name, frameCopy(frame).data);
+    this.recordDelegated(caller.name, frame.message, `Handed over by ${caller.name}`);
+    this.dispatchEvent(new CustomEvent("handoff-started", { detail: frameCopy(frame) }));
+    return handOffNote(caller.name);
+  }
+  /**
+   * Hand back to `frame`'s caller with `outcome`, and return its tail note (GENC-1737). The outcome
+   * is kept on the frame until the caller is active again and its `onHandOffReturn` has run, so a
+   * reload in between still hands back; the frame then goes, before the caller's model call.
+   */
+  async handBack(frame, outcome) {
+    frame.outcome = outcome;
+    this.handOffsThisTurn += 1;
+    const remaining = this.handOffStack.filter((f) => f !== frame);
+    const caller = this.agentNamed(frame.caller);
+    if (!caller) {
+      this.handOffStack = remaining;
+      this.unwound(frame, "agent-removed");
+      return void 0;
+    }
+    await this.agentSession.resume(caller, remaining.length > 0 || isStateful(caller));
+    const live2 = this.agentSession.getActive() ?? caller;
+    this.applyAgent(live2, frame.target);
+    if (outcome.kind === "completed" && outcome.message) {
+      this.recordDelegated(frame.target, outcome.message, `Handed back by ${frame.target}`);
+    }
+    await callHandOffHook(
+      live2.name,
+      "onHandOffReturn",
+      () => live2.onHandOffReturn?.(structuredClone(outcome), frameCopy(frame))
+    );
+    this.handOffStack = remaining;
+    this.dispatchEvent(new CustomEvent("handoff-returned", { detail: frameCopy(frame) }));
+    return handBackNote(frame, outcome);
+  }
+  /** The top frame, when `agent` is its target. */
+  topFrameFor(agent) {
+    const top = this.handOffStack[this.handOffStack.length - 1];
+    return top?.target === agent ? top : void 0;
+  }
+  /** The target's last reply since its brief, for a target that released without a summary. */
+  lastReply(frame) {
+    const history = this.chatDriver.getHistory();
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+      const m = history[i];
+      if (m.role === "user" && m.delegate === frame.caller) return void 0;
+      if (m.role === "assistant" && m.agentName === frame.target && reachesProvider(m) && m.content?.trim()) {
+        return m.content;
+      }
+    }
+    return void 0;
+  }
+  /** The brief, in the transcript as a message the caller sent on the user's behalf. */
+  recordDelegated(from, message, framing) {
+    const history = this.chatDriver.getHistory();
+    this.chatDriver.loadHistory([
+      ...history,
+      {
+        role: "user",
+        content: message,
+        delegate: from,
+        delegateFraming: framing,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    ]);
+    this.dispatchEvent(
+      new CustomEvent("history-updated", { detail: this.chatDriver.getHistory() })
+    );
+  }
+  /** End `frame` with `kind` and no hand-back, for the host. */
+  unwound(frame, kind) {
+    frame.outcome = { kind };
+    this.dispatchEvent(new CustomEvent("handoff-unwound", { detail: frameCopy(frame) }));
+  }
+  /** {@inheritDoc AiDriver.getHandOffStack} */
+  getHandOffStack() {
+    return this.handOffStack.map(frameCopy);
+  }
+  /** {@inheritDoc AiDriver.restoreHandOffStack} */
+  restoreHandOffStack(saved, savedStates, interrupted) {
+    this.handOffStack = [];
+    this.pendingHandBack = void 0;
+    const kept = [];
+    const unwoundTargets = /* @__PURE__ */ new Set();
+    for (const frame of parseHandOffFrames(saved)) {
+      const caller = this.agents.find((a) => a.name === frame.caller);
+      const outcome = frame.outcome;
+      if (!caller) {
+        this.unwound(frame, "agent-removed");
+      } else if (interrupted || caller.serialize && savedStates?.[caller.name] === void 0) {
+        this.unwound(frame, "state-lost");
+      } else {
+        kept.push(frame);
+        continue;
+      }
+      this.agentSession.setHandOffData(frame.caller, void 0);
+      unwoundTargets.add(frame.target);
+      const below = kept[kept.length - 1];
+      if (below?.target === frame.caller) {
+        below.target = frame.target;
+        if (outcome) below.outcome = outcome;
+      }
+    }
+    const top = kept[kept.length - 1];
+    if (top && !top.outcome && !this.agents.some((a) => a.name === top.target)) {
+      top.outcome = { kind: "agent-removed" };
+    }
+    this.handOffStack = kept;
+    this.chatDriver.suspendRestoredActivations(kept.map((f) => f.caller));
+    const droppedLocks = [...unwoundTargets].filter((name) => {
+      const target = this.agents.find((a) => a.name === name);
+      return !!target && !isStateful(target) && !kept.some((f) => f.target === name);
+    });
+    const dropped = droppedLocks.length ? { droppedLocks } : {};
+    if (!top?.outcome) return dropped;
+    this.pendingHandBack = { frame: top, resumed: false };
+    return { ...dropped, resume: { agent: top.caller, note: handBackNote(top, top.outcome) } };
+  }
+  /** {@inheritDoc AiDriver.unwindHandOffs} */
+  async unwindHandOffs(kind) {
+    const frames = [...this.handOffStack].reverse();
+    this.handOffStack = [];
+    this.pendingHandBack = void 0;
+    this.chatDriver.endSuspendedActivations();
+    for (const frame of frames) {
+      this.unwound(frame, kind);
+      const live2 = this.agentSession.getSuspended().find((a) => a.name === frame.caller);
+      if (kind === "cleared" && live2) {
+        await callHandOffHook(
+          live2.name,
+          "onHandOffReturn",
+          () => live2.onHandOffReturn?.(structuredClone(frame.outcome), frameCopy(frame))
+        );
+      }
+    }
+  }
+  /** {@inheritDoc AiDriver.getHandOffData} */
+  getHandOffData() {
+    const live2 = [this.agentSession.getFlowOwner(), ...this.handOffStack.map((f) => f.caller)];
+    const saved = {};
+    for (const name of live2) {
+      const data = name ? this.agentSession.getHandOffData(name) : void 0;
+      if (name && data !== void 0) saved[name] = data;
+    }
+    return saved;
+  }
+  /** {@inheritDoc AiDriver.restoreHandOffData} */
+  restoreHandOffData(saved, interrupted) {
+    if (interrupted || !saved || typeof saved !== "object" || Array.isArray(saved)) return;
+    for (const [name, data] of Object.entries(saved)) this.agentSession.setHandOffData(name, data);
+  }
+  /** {@inheritDoc AiDriver.serializeWaitingCallers} */
+  serializeWaitingCallers() {
+    const states = {};
+    for (const caller of this.agentSession.getSuspended()) {
+      if (!caller.serialize) continue;
+      try {
+        const state = caller.serialize();
+        if (state !== void 0) states[caller.name] = state;
+      } catch (e) {
+        logger2.error(`OrchestratingDriver: serialize("${caller.name}") threw:`, e);
+      }
+    }
+    return states;
+  }
   /**
    * Stop the current turn (user "stop" button). Cancels the inner chat driver's
-   * in-flight request and breaks the handoff loop so no further agent turn or
-   * classify runs. The driver stays usable for the next message.
+   * in-flight request, and no further agent runs this turn, not even a hand-off's
+   * target or a hand-back. The driver stays usable for the next message.
    */
   cancel() {
     this.cancelled = true;
@@ -10128,12 +10717,8 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
       decision,
       to: agent.name,
       fallback: isFallback(agent),
-      // The BALLOT, not `this.specialists`. `index` is a position in the ballot (see its
-      // construction in `classify`), so publishing the unfiltered specialist list beside it made
-      // `candidates[index]` resolve to the wrong agent whenever `excluded` was non-empty — and the
-      // README sentence invited exactly that join. `this.specialists` stays recoverable as
-      // `candidates ∪ excluded`. Absent where nothing was put to a vote, which is more truthful
-      // than a full list. Reviewer catch on #2496.
+      // The ballot, so `candidates[index]` is the agent chosen. Absent where nothing was put to a
+      // vote, which is more truthful than a full list.
       ...ballot ? { candidates: ballot } : {},
       ...rest,
       ...usage ? { usage } : {},
@@ -10156,7 +10741,7 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
     }
     return lines.join("\n");
   }
-  async classify(input, history, contextAgent, excludeAgents = []) {
+  async classify(input, history, contextAgent) {
     const classifyStartedAt = Date.now();
     if (this.specialists.length === 1 && !this.fallback) {
       const only = this.specialists[0];
@@ -10179,27 +10764,16 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
       this.recordRouting("no-specialists", leaf, { durationMs: Date.now() - classifyStartedAt });
       return { agent: leaf, decision: "no-specialists" };
     }
-    const ballot = excludeAgents.length ? this.specialists.filter((a) => !excludeAgents.includes(a.name)) : this.specialists;
-    if (ballot.length === 0) {
-      const leaf = this.fallback ?? this.specialists[0];
-      this.recordRouting("ballot-exhausted", leaf, {
-        excluded: excludeAgents,
-        durationMs: Date.now() - classifyStartedAt
-      });
-      return { agent: leaf, decision: "ballot-exhausted" };
-    }
+    const ballot = this.specialists;
     const agentList = ballot.map((a, i) => `${i}: ${a.name} \u2014 ${a.description}`).join("\n");
     const recentMessages = this.classifierTranscript(history);
-    const continuationHint = contextAgent && isSpecialist(contextAgent) && !excludeAgents.includes(contextAgent.name) ? `
+    const continuationHint = contextAgent && isSpecialist(contextAgent) ? `
 
 The previous turn was handled by "${contextAgent.name}". If the new message is a refinement, correction, or continuation of that work, prefer "${contextAgent.name}" \u2014 unless the topic has clearly shifted to another specialist's domain.` : "";
-    const attemptedHint = excludeAgents.length ? `
-
-Already attempted this turn and handed the work on, so not listed above: ${excludeAgents.join(", ")}. Do not expect another agent to repeat their part.` : "";
-    const classifierPrompt = `You are a routing classifier. Call select_agent with the index of the best matching agent for the user message. Use -1 only if the request is entirely unrelated to every agent listed \u2014 prefer the closest match when in doubt. If the request spans multiple agents, pick the one that should act first; I will re-classify and route again once that agent is done.
+    const classifierPrompt = `You are a routing classifier. Call select_agent with the index of the best matching agent for the user message. Use -1 only if the request is entirely unrelated to every agent listed \u2014 prefer the closest match when in doubt. If the request spans multiple agents, pick the one that should act first.
 
 Agents:
-${agentList}${continuationHint}${attemptedHint}${recentMessages ? `
+${agentList}${continuationHint}${recentMessages ? `
 
 Recent conversation:
 ${recentMessages}` : ""}`;
@@ -10247,8 +10821,7 @@ ${recentMessages}` : ""}`;
             attempts,
             durationMs: Date.now() - classifyStartedAt,
             response,
-            ballot: ballot.map((a) => a.name),
-            ...excludeAgents.length ? { excluded: excludeAgents } : {}
+            ballot: ballot.map((a) => a.name)
           });
           return { agent: chosen, decision: "classified" };
         }
@@ -10269,8 +10842,7 @@ ${recentMessages}` : ""}`;
       durationMs: Date.now() - classifyStartedAt,
       ballot: ballot.map((a) => a.name),
       ...lastError ? { error: lastError } : {},
-      ...lastResponse ? { response: lastResponse } : {},
-      ...excludeAgents.length ? { excluded: excludeAgents } : {}
+      ...lastResponse ? { response: lastResponse } : {}
     };
     if (this.fallback) {
       this.recordRouting(decision, this.fallback, routingDetail);
@@ -10308,7 +10880,7 @@ ${recentMessages}` : ""}`;
     return match;
   }
   /**
-   * Append prose the ORCHESTRATOR wrote — the handoff cap, the no-specialist apology. Flagged
+   * Append prose the ORCHESTRATOR wrote — the no-specialist apology. Flagged
    * `excludeFromProvider` for the same reason the driver's own notices are: it is not something a
    * model said, and feeding it back invites the model to echo it. See
    * `ChatMessage.excludeFromProvider`.
@@ -10816,7 +11388,6 @@ export {
   OrchestratingDriver,
   PROVIDER_REFUSED_CODE,
   ProviderRefusedError,
-  REQUEST_CONTINUATION_TOOL,
   SUPPORTED_ANTHROPIC_MODEL_IDS,
   SUPPORTED_GEMINI_MODEL_IDS,
   UNROUTABLE_INSTRUCTION,