@compilr-dev/cli 0.7.4 → 0.7.5

package/dist/handlers/delegation-handlers.js

@@ -5,15 +5,30 @@
  * The deps object is SharedState passed by reference, so live mutations
  * (e.g. team set after REPL starts) work exactly as before.
  */
-import { registerDelegateHandler, registerDelegateBackgroundHandler, registerHandoffHandler, } from '../shared-handlers.js';
+import { registerDelegateHandler, registerDelegateBackgroundHandler, registerHandoffHandler, registerConsultHandler, } from '../shared-handlers.js';
 import { getDelegationTracker } from '../multi-agent/delegation-tracker.js';
+import { buildHandoffTaskMessage, buildConsultQuestionMessage, } from '@compilr-dev/sdk';
 import chalk from 'chalk';
 import { truncate } from '../ui/base/index.js';
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
 export function registerDelegationHandlers(deps) {
-    // Register delegate handler for multi-agent delegation
+    // Register delegate handler for multi-agent delegation.
+    //
+    // Behavior (per multi-agent-tools-taxonomy-spec.md §2):
+    //   - Coordinator → specialist, foreground, SYNC response.
+    //   - Approval overlay shown (preserved UX).
+    //   - On approval, specialist runs the task INLINE and the response is
+    //     captured + returned to the coordinator as the tool result. The
+    //     active speaker does NOT permanently switch — coordinator stays in
+    //     charge of the conversation.
+    //   - Specialist's history IS persisted (delegate is the "persistent" sibling
+    //     of consult — see consult handler below for the transient version).
+    //
+    // Previously (pre-spec): set `pendingDelegation` so the REPL post-turn loop
+    // would switch active agent permanently. That was effectively
+    // "handoff with approval" and didn't match the intended semantics.
     registerDelegateHandler(async (input) => {
         // Wait for event loop to process any pending tool_end events
         await new Promise((resolve) => setImmediate(resolve));
@@ -28,8 +43,8 @@ export function registerDelegationHandlers(deps) {
             };
         }
         // Validate target agent exists
-        const targetAgent = deps.team.get(input.agentId);
-        if (!targetAgent) {
+        const targetTeamAgent = deps.team.get(input.agentId);
+        if (!targetTeamAgent) {
             return {
                 success: false,
                 declined: false,
@@ -44,63 +59,74 @@ export function registerDelegationHandlers(deps) {
                 error: 'Only the coordinator can delegate tasks. Use $<agent> to switch agents manually.',
             };
         }
-        // V2 mode: use TerminalUI overlay for approval
-        if (deps.showDelegateOverlayV2) {
-            const result = await deps.showDelegateOverlayV2({
-                agentId: input.agentId,
-                agentDisplayName: targetAgent.displayName,
-                task: input.task,
-                reason: input.reason,
-            });
-            if (!result.approved) {
-                return {
-                    success: false,
-                    declined: true,
-                };
-            }
-            // Set pending delegation - REPL will handle the switch after agent finishes
-            deps.pendingDelegation = {
-                agentId: input.agentId,
-                task: input.task,
-            };
+        // Ask for user approval — V2 overlay first, ask_user_simple fallback
+        const approval = await askForDelegationApproval({
+            deps,
+            agentId: input.agentId,
+            displayName: targetTeamAgent.displayName,
+            task: input.task,
+            reason: input.reason,
+        });
+        if (approval.kind === 'no-ui') {
             return {
-                success: true,
+                success: false,
                 declined: false,
+                error: 'Delegation UI not available. Ensure you are running in interactive mode.',
             };
         }
-        // Fallback: no V2 overlay available, use simple ask_user_simple handler
-        const askHandler = deps.showAskUserSimpleOverlayV2;
-        if (askHandler) {
-            const question = input.reason
-                ? `Delegate to $${input.agentId} (${targetAgent.displayName})?\n${chalk.dim(`Reason: ${input.reason}`)}\n${chalk.dim(`Task: ${truncate(input.task, 100)}`)}`
-                : `Delegate to $${input.agentId} (${targetAgent.displayName})?\n${chalk.dim(`Task: ${truncate(input.task, 100)}`)}`;
-            const result = await askHandler({
-                question,
-                options: ['Yes', 'No'],
-                allowCustom: false,
-            });
-            if (result.skipped || result.answer === 'No') {
+        if (approval.kind === 'declined') {
+            return { success: false, declined: true };
+        }
+        // Approved → run the specialist inline. Same pattern as consult below,
+        // minus the history snapshot/restore (delegate is persistent — the
+        // specialist remembers the work).
+        if (!targetTeamAgent.agent) {
+            try {
+                await deps.team.initializeAll();
+            }
+            catch (initErr) {
                 return {
                     success: false,
-                    declined: true,
+                    declined: false,
+                    error: `Failed to initialize $${input.agentId}: ${initErr instanceof Error ? initErr.message : String(initErr)}`,
                 };
             }
-            // Set pending delegation
-            deps.pendingDelegation = {
-                agentId: input.agentId,
-                task: input.task,
+        }
+        const targetAgent = targetTeamAgent.agent;
+        if (!targetAgent) {
+            return {
+                success: false,
+                declined: false,
+                error: `Agent '$${input.agentId}' could not be initialized.`,
             };
+        }
+        // Build the delegated task message. Mirrors the delegate_background
+        // preamble's SCOPE block so the specialist knows it's a delegation.
+        const taskMessage = buildDelegateTaskMessage({
+            task: input.task,
+            reason: input.reason,
+        });
+        try {
+            const runResult = await targetAgent.run(taskMessage);
+            // Truncate very long responses to keep the coordinator's context lean.
+            const response = runResult.response.length > 2000
+                ? runResult.response.slice(0, 2000) + '\n…[truncated to 2000 chars]'
+                : runResult.response;
             return {
                 success: true,
                 declined: false,
+                response,
+                agentId: input.agentId,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                declined: false,
+                agentId: input.agentId,
+                error: `Delegate failed: ${err instanceof Error ? err.message : String(err)}`,
             };
         }
-        // No handler available
-        return {
-            success: false,
-            declined: false,
-            error: 'Delegation UI not available. Ensure you are running in interactive mode.',
-        };
     });
     // Register delegate_background handler for coordinator mode
     registerDelegateBackgroundHandler(async (input) => {
@@ -277,15 +303,167 @@ export function registerDelegationHandlers(deps) {
         }
         // Record the handoff for one-hop tracking
         deps.team.recordHandoff(input.agentId, sourceAgentId);
-        // Set pending delegation - REPL will handle the switch after agent finishes
-        // Reuses the same pendingDelegation mechanism as delegate
+        // Set pending delegation - REPL will handle the switch after agent finishes.
+        // Reuses the same pendingDelegation mechanism as delegate. We dispatch the
+        // task via `buildHandoffTaskMessage` (SDK helper) so the target receives
+        // the canonical `[Handoff from $arch]\n\nTask: …` wrapper — identical
+        // wording to what the Desktop sends on handoff, regardless of host.
+        const intent = {
+            // CLI has a single REPL session — the conversation key is implicit.
+            // SDK takes this as opaque, so any stable string is fine.
+            conversationId: 'cli',
+            sourceAgentId,
+            targetAgentId: input.agentId,
+            task: input.task,
+            reason: input.reason,
+        };
         deps.pendingDelegation = {
             agentId: input.agentId,
-            task: input.task,
+            task: buildHandoffTaskMessage(intent),
         };
         return {
             success: true,
             declined: false,
         };
     });
+    // ---------------------------------------------------------------------------
+    // consult handler — specialist-to-specialist sync borrow
+    //
+    // Unlike delegate/handoff (which set `pendingDelegation` so the REPL can
+    // run the target agent on the NEXT turn), consult must run the target
+    // INLINE during the borrower's current turn and return the answer as the
+    // tool's output. The borrower's run never yields control.
+    //
+    // Transient design: snapshot the target's history, run the synthesised
+    // question, restore the history. The target's chat is untouched.
+    //
+    // Errors are returned as `{ answer: '', error: ... }` so the borrower's
+    // LLM sees them as tool output and can decide what to do.
+    // ---------------------------------------------------------------------------
+    registerConsultHandler(async (input) => {
+        // Yield to event loop (consistent with the other handlers in this file).
+        await new Promise((resolve) => setImmediate(resolve));
+        if (!deps.team) {
+            return {
+                answer: '',
+                agentId: input.agentId,
+                error: 'Multi-agent team not initialized. Consult requires an active team.',
+            };
+        }
+        const targetTeamAgent = deps.team.get(input.agentId);
+        if (!targetTeamAgent) {
+            return {
+                answer: '',
+                agentId: input.agentId,
+                error: `Agent '${input.agentId}' not found in team.`,
+            };
+        }
+        // Auto-initialize the target if it hasn't been used yet. This used
+        // to be an error ("switch to them once first") but the friction was
+        // wrong — a coordinator asking the user to manually warm up every
+        // specialist before consult is unreasonable. team.initializeAll()
+        // is the SDK's lazy-init entry point; it skips already-initialized
+        // agents, so subsequent consults pay only the first-time cost.
+        if (!targetTeamAgent.agent) {
+            try {
+                await deps.team.initializeAll();
+            }
+            catch (initErr) {
+                return {
+                    answer: '',
+                    agentId: input.agentId,
+                    error: `Failed to initialize $${input.agentId}: ${initErr instanceof Error ? initErr.message : String(initErr)}`,
+                };
+            }
+        }
+        const targetAgent = targetTeamAgent.agent;
+        if (!targetAgent) {
+            return {
+                answer: '',
+                agentId: input.agentId,
+                error: `Agent '$${input.agentId}' could not be initialized.`,
+            };
+        }
+        const sourceAgentId = deps.team.activeAgentId;
+        const consultMessage = buildConsultQuestionMessage({
+            sourceAgentId,
+            question: input.question,
+            context: input.context,
+        });
+        // Snapshot the target's history so the consult is transient — the
+        // target's actual chat shouldn't grow a record of consults received.
+        const historySnapshot = targetAgent.getHistory();
+        try {
+            // Run inline. No onEvent forwarder → the target's tool calls and
+            // streaming text don't render to the REPL (we want the source agent's
+            // voice foregrounded; the answer comes back as a tool result).
+            const runResult = await targetAgent.run(consultMessage);
+            return { answer: runResult.response, agentId: input.agentId };
+        }
+        catch (err) {
+            return {
+                answer: '',
+                agentId: input.agentId,
+                error: `Consult failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        finally {
+            // Restore history regardless of success/failure — even a partial run
+            // mutates the target's message log, and we promised it'd be transient.
+            try {
+                await targetAgent.setHistory(historySnapshot);
+            }
+            catch {
+                // History restore is best-effort; if it fails the next message the
+                // user sends to the target will see the consult artefacts. Logging
+                // happens via the agent's own error path.
+            }
+        }
+    });
+}
+/**
+ * Show the delegation approval overlay (V2 if available, ask_user_simple
+ * fallback otherwise). Centralises the dual-path logic that the old
+ * delegate handler inlined twice.
+ */
+async function askForDelegationApproval(args) {
+    const { deps, agentId, displayName, task, reason } = args;
+    // V2 mode: TerminalUI overlay
+    if (deps.showDelegateOverlayV2) {
+        const result = await deps.showDelegateOverlayV2({
+            agentId,
+            agentDisplayName: displayName,
+            task,
+            reason,
+        });
+        return result.approved ? { kind: 'approved' } : { kind: 'declined' };
+    }
+    // Fallback: ask_user_simple
+    if (deps.showAskUserSimpleOverlayV2) {
+        const question = reason
+            ? `Delegate to $${agentId} (${displayName})?\n${chalk.dim(`Reason: ${reason}`)}\n${chalk.dim(`Task: ${truncate(task, 100)}`)}`
+            : `Delegate to $${agentId} (${displayName})?\n${chalk.dim(`Task: ${truncate(task, 100)}`)}`;
+        const result = await deps.showAskUserSimpleOverlayV2({
+            question,
+            options: ['Yes', 'No'],
+            allowCustom: false,
+        });
+        if (result.skipped || result.answer === 'No')
+            return { kind: 'declined' };
+        return { kind: 'approved' };
+    }
+    return { kind: 'no-ui' };
+}
+/**
+ * Build the delegated task message handed to the specialist. Mirrors the
+ * delegate_background preamble's SCOPE block so the specialist knows it
+ * was a delegation (versus a direct turn from the user or a consult).
+ */
+function buildDelegateTaskMessage(args) {
+    const { task, reason } = args;
+    const lines = ['[DELEGATION from coordinator]'];
+    if (reason)
+        lines.push(`Reason: ${reason}`);
+    lines.push('', 'SCOPE: Focus ONLY on the task below. Do NOT pick up, start, or ask', 'about other tasks. Report your final result when done.', '', 'Task:', task);
+    return lines.join('\n');
 }

package/dist/handlers/interactive-flow-handlers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * build_interactive_flow handler factory — mirrors ask-user-handlers.ts.
+ *
+ * Registers a handler that:
+ *   1. Waits for any pending tool_end events to drain
+ *   2. Flushes accumulated agent text so the wizard doesn't crowd the
+ *      conversation log
+ *   3. For background agents, enqueues the request via the pending-
+ *      requests manager (user services it through /pending)
+ *   4. For foreground agents, shows InteractiveFlowOverlayV2
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-cli/interactive-flow-cli-spec.md
+ */
+import { type InteractiveFlowResult, type Flow } from '../shared-handlers.js';
+export interface InteractiveFlowHandlerDeps {
+    flushTextBuffer?: () => void;
+    getActiveBackgroundAgentId?: () => string | null;
+    isBackgroundAgent?: (agentId?: string) => boolean;
+    getBackgroundAgentInfo?: (agentId: string) => {
+        mascot: string;
+    } | null;
+    showInteractiveFlowOverlayV2?: (options: {
+        flow: Flow;
+    }) => Promise<InteractiveFlowResult>;
+}
+export declare function registerInteractiveFlowHandlers(deps: InteractiveFlowHandlerDeps): void;

package/dist/handlers/interactive-flow-handlers.js

@@ -0,0 +1,61 @@
+/**
+ * build_interactive_flow handler factory — mirrors ask-user-handlers.ts.
+ *
+ * Registers a handler that:
+ *   1. Waits for any pending tool_end events to drain
+ *   2. Flushes accumulated agent text so the wizard doesn't crowd the
+ *      conversation log
+ *   3. For background agents, enqueues the request via the pending-
+ *      requests manager (user services it through /pending)
+ *   4. For foreground agents, shows InteractiveFlowOverlayV2
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-cli/interactive-flow-cli-spec.md
+ */
+import { registerInteractiveFlowHandler, } from '../shared-handlers.js';
+import { getPendingRequestsManager } from '../multi-agent/index.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function registerInteractiveFlowHandlers(deps) {
+    registerInteractiveFlowHandler(async (input) => {
+        // Wait for any pending tool_end events to drain
+        await new Promise((resolve) => setImmediate(resolve));
+        // Flush accumulated text BEFORE showing the overlay
+        deps.flushTextBuffer?.();
+        // Background-agent routing — enqueue via pending-requests manager
+        const backgroundAgentId = deps.getActiveBackgroundAgentId?.();
+        if (backgroundAgentId && deps.isBackgroundAgent?.(backgroundAgentId)) {
+            const agentInfo = deps.getBackgroundAgentInfo?.(backgroundAgentId);
+            const pendingManager = getPendingRequestsManager();
+            try {
+                const response = await pendingManager.enqueue({
+                    agentId: backgroundAgentId,
+                    mascot: agentInfo?.mascot ?? '[•_•]',
+                    type: 'question',
+                    prompt: input.flow.title,
+                    context: {
+                        toolType: 'build_interactive_flow',
+                        originalInput: input,
+                    },
+                });
+                return response.overlayResult;
+            }
+            catch {
+                // Request was cancelled — return aborted result
+                return {
+                    completed: false,
+                    path: [],
+                    answers: {},
+                    answerLabels: {},
+                    abortReason: 'unknown',
+                    durationMs: 0,
+                };
+            }
+        }
+        // Foreground — show the overlay
+        if (!deps.showInteractiveFlowOverlayV2) {
+            throw new Error('build_interactive_flow overlay not initialized');
+        }
+        return deps.showInteractiveFlowOverlayV2({ flow: input.flow });
+    });
+}

package/dist/handlers/propose-alternatives-handlers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * propose_alternatives handler factory — mirrors ask-user-handlers.ts.
+ *
+ * Registers a handler that:
+ *   1. Waits for any pending tool_end events to drain
+ *   2. Flushes accumulated agent text so the overlay doesn't crowd the
+ *      conversation log
+ *   3. For background agents, enqueues the request via the pending-
+ *      requests manager (user services it through /pending)
+ *   4. For foreground agents, shows ProposeAlternativesOverlayV2
+ *
+ * The deps object is SharedState passed by reference, so live overlay
+ * callbacks wired after REPL starts work as expected.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-cli/propose-alternatives-spec.md
+ */
+import { type Alternative } from '../shared-handlers.js';
+export interface ProposeAlternativesHandlerDeps {
+    flushTextBuffer?: () => void;
+    getActiveBackgroundAgentId?: () => string | null;
+    isBackgroundAgent?: (agentId?: string) => boolean;
+    getBackgroundAgentInfo?: (agentId: string) => {
+        mascot: string;
+    } | null;
+    showProposeAlternativesOverlayV2?: (options: {
+        question: string;
+        context?: string;
+        alternatives: Alternative[];
+    }) => Promise<{
+        chosenIndex: number;
+        chosenTitle: string;
+        notes?: string;
+        rejected: boolean;
+    }>;
+}
+export declare function registerProposeAlternativesHandlers(deps: ProposeAlternativesHandlerDeps): void;

package/dist/handlers/propose-alternatives-handlers.js

@@ -0,0 +1,65 @@
+/**
+ * propose_alternatives handler factory — mirrors ask-user-handlers.ts.
+ *
+ * Registers a handler that:
+ *   1. Waits for any pending tool_end events to drain
+ *   2. Flushes accumulated agent text so the overlay doesn't crowd the
+ *      conversation log
+ *   3. For background agents, enqueues the request via the pending-
+ *      requests manager (user services it through /pending)
+ *   4. For foreground agents, shows ProposeAlternativesOverlayV2
+ *
+ * The deps object is SharedState passed by reference, so live overlay
+ * callbacks wired after REPL starts work as expected.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-cli/propose-alternatives-spec.md
+ */
+import { registerProposeAlternativesHandler, } from '../shared-handlers.js';
+import { getPendingRequestsManager } from '../multi-agent/index.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function registerProposeAlternativesHandlers(deps) {
+    registerProposeAlternativesHandler(async (input) => {
+        // Wait for any pending tool_end events to drain
+        await new Promise((resolve) => setImmediate(resolve));
+        // Flush accumulated text BEFORE showing the overlay
+        deps.flushTextBuffer?.();
+        // Background-agent routing — enqueue via pending-requests manager
+        const backgroundAgentId = deps.getActiveBackgroundAgentId?.();
+        if (backgroundAgentId && deps.isBackgroundAgent?.(backgroundAgentId)) {
+            const agentInfo = deps.getBackgroundAgentInfo?.(backgroundAgentId);
+            const pendingManager = getPendingRequestsManager();
+            try {
+                const response = await pendingManager.enqueue({
+                    agentId: backgroundAgentId,
+                    mascot: agentInfo?.mascot ?? '[•_•]',
+                    type: 'question',
+                    prompt: input.question,
+                    context: {
+                        toolType: 'propose_alternatives',
+                        originalInput: input,
+                    },
+                });
+                return response.overlayResult;
+            }
+            catch {
+                // Request was cancelled — fall back to a rejected result
+                return {
+                    chosenIndex: 0,
+                    chosenTitle: input.alternatives[0]?.title ?? '',
+                    rejected: true,
+                };
+            }
+        }
+        // Foreground — show the overlay
+        if (!deps.showProposeAlternativesOverlayV2) {
+            throw new Error('propose_alternatives overlay not initialized');
+        }
+        return deps.showProposeAlternativesOverlayV2({
+            question: input.question,
+            context: input.context,
+            alternatives: input.alternatives,
+        });
+    });
+}

package/dist/index.js

@@ -36,8 +36,9 @@ import { cleanupStaleDiffs } from './ui/vscode-diff-ipc.js';
 import { createPermissionHandler } from './handlers/permission-handler.js';
 import { registerDelegationHandlers } from './handlers/delegation-handlers.js';
 import { registerAskUserHandlers } from './handlers/ask-user-handlers.js';
-import { EpisodeRecorder, FileEpisodeStore, setGlobalEpisodeStore } from './episodes/index.js';
-import { updateWorkSummaryAnchor } from './episodes/work-summary-anchor.js';
+import { registerProposeAlternativesHandlers } from './handlers/propose-alternatives-handlers.js';
+import { registerInteractiveFlowHandlers } from './handlers/interactive-flow-handlers.js';
+import { EpisodeRecorder, FileEpisodeStore, setGlobalEpisodeStore, updateWorkSummaryAnchor, } from './episodes/index.js';
 import { getSessionsPath } from './settings/paths.js';
 import * as path from 'path';
 perf('imports-done');
@@ -447,6 +448,8 @@ async function main() {
     const onPermissionRequest = createPermissionHandler(sharedState);
     // Register ask_user and ask_user_simple handlers
     registerAskUserHandlers(sharedState);
+    registerProposeAlternativesHandlers(sharedState);
+    registerInteractiveFlowHandlers(sharedState);
     // Register delegate, delegate_background, and handoff handlers for multi-agent delegation
     registerDelegationHandlers(sharedState);
     // Create iteration limit handler that shows overlay
@@ -712,6 +715,14 @@ async function main() {
         onAskUserReady: (showOverlay) => {
             sharedState.showAskUserOverlayV2 = showOverlay;
         },
+        // Set up propose_alternatives V2 overlay callback
+        onProposeAlternativesReady: (showOverlay) => {
+            sharedState.showProposeAlternativesOverlayV2 = showOverlay;
+        },
+        // Set up build_interactive_flow V2 overlay callback
+        onInteractiveFlowReady: (showOverlay) => {
+            sharedState.showInteractiveFlowOverlayV2 = showOverlay;
+        },
         // Set up iteration_limit V2 overlay callback
         onIterationLimitReady: (showOverlay) => {
             sharedState.showIterationLimitOverlayV2 = showOverlay;

package/dist/repl-v2.d.ts

@@ -15,6 +15,8 @@ import { type PermissionResult, type PermissionOverlayV2Options } from './ui/ove
 import { type AskUserSimpleOptionsV2, type AskUserSimpleResultV2 } from './ui/overlay/impl/ask-user-simple-overlay-v2.js';
 import { type GuardrailConfirmOptionsV2, type GuardrailConfirmResultV2 } from './ui/overlay/impl/guardrail-overlay-v2.js';
 import { type AskUserOptionsV2, type AskUserResultV2 } from './ui/overlay/impl/ask-user-overlay-v2.js';
+import { type ProposeAlternativesOptionsV2, type ProposeAlternativesResultV2 } from './ui/overlay/impl/propose-alternatives-overlay-v2.js';
+import { type InteractiveFlowOptionsV2, type InteractiveFlowResultV2 } from './ui/overlay/impl/interactive-flow-overlay-v2.js';
 import { type IterationLimitOptionsV2, type IterationLimitResultV2 } from './ui/overlay/impl/iteration-limit-overlay-v2.js';
 export interface DelegateOverlayOptions {
     agentId: string;
@@ -70,6 +72,16 @@ export interface ReplV2Options {
      * Allows index.ts to use V2 overlay for multi-question forms.
      */
     onAskUserReady?: (showOverlay: (options: AskUserOptionsV2) => Promise<AskUserResultV2>) => void;
+    /**
+     * Callback invoked when propose_alternatives overlay is ready.
+     * Allows index.ts to wire showProposeAlternativesOverlayV2 on sharedState.
+     */
+    onProposeAlternativesReady?: (showOverlay: (options: ProposeAlternativesOptionsV2) => Promise<ProposeAlternativesResultV2>) => void;
+    /**
+     * Callback invoked when build_interactive_flow overlay is ready.
+     * Allows index.ts to wire showInteractiveFlowOverlayV2 on sharedState.
+     */
+    onInteractiveFlowReady?: (showOverlay: (options: InteractiveFlowOptionsV2) => Promise<InteractiveFlowResultV2>) => void;
     /**
      * Callback invoked when iteration_limit overlay is ready.
      * Allows index.ts to use V2 overlay for iteration limit prompts.
@@ -238,6 +250,8 @@ export declare class ReplV2 {
     private readonly onAskUserSimpleReady?;
     private readonly onGuardrailReady?;
     private readonly onAskUserReady?;
+    private readonly onProposeAlternativesReady?;
+    private readonly onInteractiveFlowReady?;
     private readonly onIterationLimitReady?;
     private readonly onAgentFinish?;
     private readonly onSuggestionReady?;
@@ -264,6 +278,7 @@ export declare class ReplV2 {
     private sessionRequests;
     private textAccumulator;
     private readonly bashAbortControllers;
+    private readonly specialistToolsRegistered;
     constructor(options?: ReplV2Options);
     /**
      * Flush accumulated agent text to the UI.
@@ -354,6 +369,57 @@ export declare class ReplV2 {
      * Callers handle their own messaging (different styles/wording per context).
      */
     private switchAgent;
+    /**
+     * Register multi-agent tools (consult always, handoff for specialists)
+     * on the agent's underlying Agent using SDK factories.
+     *
+     * Tool grants:
+     * - **consult**: everyone (coordinator AND specialists). Lightweight
+     *   "ask another agent a focused question" tool. Originally specced as
+     *   specialist-only, but empirical evidence (session 220) showed the
+     *   coordinator's LLM grabs the wrong tool (e.g. `suggest`) when the
+     *   user says "consult $pm" because no tool by that name was in its
+     *   registry. delegate is too heavyweight for a quick question.
+     * - **handoff**: specialists only. Coordinators delegate, they don't
+     *   pass the baton. $default → specialist already has delegate.
+     * - **delegate / delegate_background**: coordinator only, via the
+     *   existing CLI tool-array path. Not touched here.
+     *
+     * Why lazy: the SDK factories need `team` + `currentAgentId` at
+     * construction time. The CLI's tool array is built at module load
+     * when neither is known.
+     *
+     * Dedupe via `specialistToolsRegistered` set — tools are registered
+     * once per agent for the lifetime of the REPL. Mirrors Desktop's
+     * pattern in `agent-manager.ts:registerDelegateToolsIfNeeded`.
+     *
+     * Called from:
+     * - `switchAgent` (every agent switch — covers specialists).
+     * - `restoreTeamForPrefix` (team restoration — covers $default at
+     *   startup, since the coordinator is never switchTo'd from outside).
+     */
+    /**
+     * Called whenever `this.team` is reassigned (project switch, team
+     * restoration). The SDK's createConsultTool factory captures the `team`
+     * argument in its closure at construction time, so a tool registered
+     * against the old team has a stale roster view. We must:
+     *   1. Unregister the stale consult/handoff tools from $default's
+     *      registry (Agent.registerTools throws on duplicate-name, it
+     *      does not replace).
+     *   2. Re-register fresh tools bound to the new team.
+     *
+     * $default's underlying Agent is preserved across team swaps (the new
+     * team is set as default via setDefaultAgent), so its tool registry
+     * accumulates stale tools. Specialists' Agents are fresh after a swap,
+     * so they don't have stale tools to clean up — clearing the dedupe set
+     * is enough; they'll re-register on demand via switchAgent.
+     *
+     * Without this, `consult($pm)` from $default reports "no specialists
+     * available" because the closure references the fresh-startup team
+     * (which only had $default) instead of the restored/built team.
+     */
+    private rebindMultiAgentToolsAfterTeamSwap;
+    private registerMultiAgentTools;
     /**
      * Bring a background agent to foreground.
      * Validates the agent has a background session, then delegates to switchAgent().