chainlesschain 0.162.193 → 0.162.198

package/src/repl/agent-repl.js

@@ -25,6 +25,7 @@ import path from "path";
 import { randomUUID } from "node:crypto";
 import { isPromise, isProxy } from "node:util/types";
 import { logger } from "../lib/logger.js";
+import { issueMcpStdioExecutionAuthority } from "../lib/mcp-stdio-execution-authority.js";
 import { getPlanModeManager, PlanState } from "../lib/plan-mode.js";
 import { createVimState, feedNormalKey } from "../lib/repl-vim.js";
 import {
@@ -123,9 +124,10 @@ import {
 } from "../runtime/agent-core.js";
 import { formatBackgroundTasks } from "./tasks-status.js";
 import { expandFileRefsAsync } from "../runtime/file-ref-expander.js";
-import { prepareVisionTurn } from "../lib/image-input.js";
+import { prepareVisionTurn, resolveVisionLlm } from "../lib/image-input.js";
 import { composeSystemPrompt } from "../runtime/system-prompt.js";
 import { installPipeSafety } from "../runtime/pipe-safety.js";
+import { installOutputBackpressure } from "../runtime/output-backpressure.js";
 import {
   makeFallbackChatFn,
   normalizeFallbackModels,
@@ -145,6 +147,10 @@ import {
 } from "./btw-command.js";
 import { shouldStreamLive } from "./stream-decision.js";
 import { emptyTurnNotice } from "./empty-turn-notice.js";
+import {
+  createPromptInteractionSurface,
+  mergeClipboardImageChips,
+} from "./prompt-interactions.js";
 import {
   buildPermissionPrompt,
   resolveAskIdleTimeoutMs,
@@ -319,6 +325,9 @@ async function executeTool(name, args) {
  * unit-testable via the `options._coreLoop` injection seam.
  */
 export async function agentLoop(messages, options) {
+  const writeOut =
+    options.writeOut || ((text) => process.stdout.write(String(text)));
+  const waitForOutput = options.waitForOutput;
   // Resume-degenerate role merge (Claude Code 2.1.187 parity), gated by the
   // one-shot `mergeRoles` flag so it fires only on the first model call after
   // resuming a session whose prior run produced no assistant response. Collapse
@@ -339,7 +348,7 @@ export async function agentLoop(messages, options) {
   const onProviderFallback =
     options.onProviderFallback ||
     ((info) =>
-      process.stdout.write(
+      writeOut(
         chalk.yellow(
           `\n  ⚠️  ${info.message || `已从 "${info.from}" 切换到 "${info.to}"`}\n`,
         ),
@@ -376,7 +385,7 @@ export async function agentLoop(messages, options) {
         event.type === "managed-checkpoint-error" || event.coverage === "none"
           ? chalk.yellow
           : chalk.gray;
-      process.stdout.write(render(`${managedCheckpointLine}\n`));
+      writeOut(render(`${managedCheckpointLine}\n`));
     } else if (event.type === "checkpoint") {
       // Remember which file snapshot lines up with the live conversation so
       // `/rewind <n>` can restore code + conversation together (Claude-Code
@@ -389,7 +398,7 @@ export async function agentLoop(messages, options) {
           tool: event.tool,
         });
       }
-      process.stdout.write(
+      writeOut(
         chalk.gray(`  ⎌ checkpoint ${event.id} (before ${event.tool})\n`),
       );
     } else if (event.type === "tool-executing") {
@@ -398,7 +407,7 @@ export async function agentLoop(messages, options) {
         args: event.args,
         startedAt: options.now ? options.now() : Date.now(),
       };
-      process.stdout.write(
+      writeOut(
         chalk.gray(
           `  [${event.tool}] ${formatToolArgs(event.tool, event.args)}\n`,
         ),
@@ -434,9 +443,7 @@ export async function agentLoop(messages, options) {
         }
       }
       if (event.error || event.result?.error) {
-        process.stdout.write(
-          chalk.red(`  Error: ${event.error || event.result?.error}\n`),
-        );
+        writeOut(chalk.red(`  Error: ${event.error || event.result?.error}\n`));
         // Record policy denials (not plain tool failures) into the caller's
         // denial log for review via `/permissions denials` (Claude-Code 2.1.193
         // recent denials). Caller passes the session log (mirrors checkpointMarks)
@@ -473,13 +480,13 @@ export async function agentLoop(messages, options) {
           const sid = options?.sessionId;
           const policy = approval.policy || "strict";
           if (sid && policy === "strict") {
-            process.stdout.write(
+            writeOut(
               chalk.yellow(
                 `  Hint: relax policy with  cc session policy ${sid} --set trusted\n`,
               ),
             );
           } else if (sid) {
-            process.stdout.write(
+            writeOut(
               chalk.yellow(
                 `  Hint: per-session policy is "${policy}" — see  cc session policy ${sid}\n`,
               ),
@@ -487,26 +494,26 @@ export async function agentLoop(messages, options) {
           }
         }
       } else if (event.result?.success) {
-        process.stdout.write(chalk.green(`  Done\n`));
+        writeOut(chalk.green(`  Done\n`));
       }
     } else if (event.type === "thinking") {
       // Intermediate-step reasoning (before a tool call) — dimmed, inline.
       if (process.env.CC_REPL_THINKING !== "0" && event.text) {
-        process.stdout.write(
+        writeOut(
           "\n" + chalk.dim("💭 " + event.text.replace(/\n/g, "\n   ")) + "\n",
         );
       }
     } else if (event.type === "token-usage") {
       usageEvents.push(event);
     } else if (event.type === "iteration-warning") {
-      process.stdout.write(chalk.yellow(`\n  ${event.message}\n`));
+      writeOut(chalk.yellow(`\n  ${event.message}\n`));
     } else if (event.type === "iteration-budget-exhausted") {
-      process.stdout.write(
-        chalk.red(`\n  [Budget Exhausted] ${event.budget}\n`),
-      );
+      writeOut(chalk.red(`\n  [Budget Exhausted] ${event.budget}\n`));
     } else if (event.type === "response-complete") {
+      await waitForOutput?.();
       return { content: event.content, usageEvents, thinking: event.thinking };
     }
+    await waitForOutput?.();
   }
   return { content: "", usageEvents };
 }
@@ -1930,7 +1937,12 @@ export function createReplMcpHostRuntimeManager(dependencies = {}) {
     }
 
     const sink = persistLedger
-      ? createLedgerSink(sessionId, { appendEvent: appendLedgerEvent })
+      ? createLedgerSink(
+          sessionId,
+          appendLedgerEvent === appendAuthorityEvent
+            ? { recovery }
+            : { appendEvent: appendLedgerEvent },
+        )
       : null;
     const sharedController =
       !verifiedRecovery && current?.sessionId === sessionId
@@ -2064,27 +2076,93 @@ export async function startAgentRepl(options = {}) {
 }
 
 async function startAgentReplInWorkspace(options = {}, startupAdmission) {
+  let failureHandler = null;
+  let disposePipeSafety = null;
+  const flow = installOutputBackpressure({
+    stdout: process.stdout,
+    stderr: process.stderr,
+    maxQueuedBytes: options.outputBackpressureMaxBytes,
+    onFailure: (error) => failureHandler?.(error),
+  });
+  let restored = false;
+  const outputScope = {
+    flow,
+    setFailureHandler(handler) {
+      failureHandler = handler;
+    },
+    setPipeDisposer(disposer) {
+      disposePipeSafety = disposer;
+    },
+    restore() {
+      if (restored) return;
+      restored = true;
+      disposePipeSafety?.();
+      flow.restore();
+    },
+  };
+  try {
+    return await startAgentReplInWorkspaceOwned(
+      options,
+      startupAdmission,
+      outputScope,
+    );
+  } catch (error) {
+    outputScope.restore();
+    throw error;
+  }
+}
+
+async function startAgentReplInWorkspaceOwned(
+  options = {},
+  startupAdmission,
+  outputScope,
+) {
   // EPIPE guard: if the REPL's stdout is piped and the consumer closes (e.g.
   // `cc agent | head`), the async stream `error` would otherwise crash the
   // process. Route a broken pipe into the REPL's own graceful shutdown (the
   // rl "close" handler — MCP disconnect, kill background tasks) when the
-  // interface exists, else exit cleanly. `_replClosing` makes it fire once so a
-  // cleanup write that also EPIPEs can't loop. `_replRl` is set when rl is built.
+  // interface and its close handler exist. `_replClosing` makes it fire once so
+  // a cleanup write that also EPIPEs can't loop. An early EPIPE remains pending
+  // until the close handler is attached; it never skips directly to exit.
   let _replRl = null;
   let _replClosing = false;
-  installPipeSafety(undefined, () => {
+  let _replCloseReady = false;
+  let _replCleanupStarted = false;
+  let _turnAbort = null;
+  let _replOutputFailure = null;
+  const _requestReplOutputClose = (error) => {
+    if (error && !_replOutputFailure) _replOutputFailure = error;
+    if (error) {
+      process.exitCode = error.code === "EPIPE" ? 0 : 1;
+      _turnAbort?.abort(error);
+    }
     if (_replClosing) return;
     _replClosing = true;
-    if (_replRl) {
+    if (_replRl && _replCloseReady) {
       try {
-        _replRl.close(); // triggers the graceful "close" cleanup → process.exit
-        return;
+        _replRl.close(); // triggers the graceful "close" cleanup
       } catch {
-        /* fall through to a bare exit */
+        // The close handler owns shutdown. Leaving exitCode set allows the
+        // event loop to drain without bypassing the teardown lifecycle.
       }
     }
-    process.exit(0);
-  });
+  };
+  const _replOutputFlow = outputScope.flow;
+  outputScope.setFailureHandler(_requestReplOutputClose);
+  const _disposeReplPipeSafety = installPipeSafety(undefined, () =>
+    _requestReplOutputClose(
+      Object.assign(new Error("REPL output pipe closed"), { code: "EPIPE" }),
+    ),
+  );
+  outputScope.setPipeDisposer(_disposeReplPipeSafety);
+  const _waitForReplOutput = async () => {
+    try {
+      await _replOutputFlow.wait();
+      return true;
+    } catch {
+      return false;
+    }
+  };
   const { useJsonl, candidate: _startupJsonlResume } = startupAdmission;
   let model = options.model || "qwen2.5:7b";
   let provider = options.provider || "ollama";
@@ -2134,6 +2212,8 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
   // an auto-detected image path so the REPL switches to a vision-capable model
   // for that turn only (resolveVisionLlm falls back to the default when unset).
   let _visionModel;
+  let _promptInteractionConfig = {};
+  let _persistPromptSuggestionsEnabled = null;
   // Hard stream inactivity timeout override (config.llm.streamStallTimeoutMs,
   // ms): a stream silent that long is aborted + retried instead of hanging.
   // Unset → agent-core's 180s default (matches cc chat/ask). Set to 0 to
@@ -2148,8 +2228,11 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
   // CC_PERMISSION_ASK_TIMEOUT_MS env > config permissions.askTimeoutMs > off.
   let _askIdleTimeoutMs = resolveAskIdleTimeoutMs();
   try {
-    const { loadConfig } = await import("../lib/config-manager.js");
-    const _cfg = loadConfig();
+    const configManager = await import("../lib/config-manager.js");
+    const _cfg = configManager.loadConfig();
+    _promptInteractionConfig = _cfg || {};
+    _persistPromptSuggestionsEnabled = (enabled) =>
+      configManager.setConfigValue("cli.promptSuggestions", enabled === true);
     _visionModel = _cfg?.llm?.visionModel || undefined;
     _autoPinCfgValue = _cfg?.context?.autoPin;
     _askIdleTimeoutMs = resolveAskIdleTimeoutMs({
@@ -2979,7 +3062,15 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
             let connected = 0;
             for (const [name, cfg] of serverEntries) {
               try {
-                await _bundleMcpClient.connect(name, cfg);
+                const authorizedConfig = { ...cfg };
+                authorizedConfig.mcpStdioExecutionAuthority =
+                  issueMcpStdioExecutionAuthority({
+                    serverName: name,
+                    config: authorizedConfig,
+                    approvalKind: "explicit-config",
+                    approvalSource: `agent-bundle:${path.resolve(options.bundlePath)}`,
+                  });
+                await _bundleMcpClient.connect(name, authorizedConfig);
                 connected += 1;
               } catch (mcpErr) {
                 logger.log(
@@ -3588,11 +3679,13 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
           "/note-next",
           "/output-style",
           "/permissions",
+          "/paste-image",
           "/plan",
           "/pr-comments",
           "/profile",
           "/provider",
           "/quit",
+          "/recap",
           "/reindex",
           "/release-notes",
           "/reload-plugins",
@@ -3606,7 +3699,9 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
           "/stats",
           "/status",
           "/statusline",
+          "/stash",
           "/sub-agents",
+          "/suggestions",
           "/task",
           "/tasks",
           "/terminal-setup",
@@ -3617,6 +3712,7 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
           "/ultrathink",
           "/vim",
           "/voice",
+          "/editor",
         ],
     // User/project custom commands (.claude/commands/*.md) join TAB completion
     // alongside the built-ins above. Sync + best-effort; the completer
@@ -3660,6 +3756,28 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
   // "close" cleanup instead of a bare exit.
   _replRl = rl;
 
+  // Prompt-side interaction modules share the production readline surface.
+  // A per-REPL registry avoids singleton handlers retaining an old session.
+  const _promptInteractionSurface = createPromptInteractionSurface({
+    readline: rl,
+    config: _promptInteractionConfig,
+    keybindings: _promptInteractionConfig,
+    getSessionId: () => sessionId,
+    getSuggestionContext: () => ({ messages: messages.slice() }),
+    persistSuggestionEnabled: _persistPromptSuggestionsEnabled,
+    clipboardBinding: options.clipboardBinding || null,
+    generateSuggestions: options.generatePromptSuggestions,
+    suggestionDebounceMs: options.promptSuggestionDebounceMs,
+    screenReader: _screenReaderMode,
+    write: (text) => process.stdout.write(String(text)),
+    writeError: (text) => process.stderr.write(String(text)),
+    getColumns: () => process.stdout.columns || 80,
+  });
+  const _promptInteractions = _promptInteractionSurface.controller;
+  for (const diagnostic of _promptInteractions.diagnostics().keybindingErrors) {
+    logger.warn(`prompt keybinding ignored: ${diagnostic}`);
+  }
+
   // MCP elicitation in the interactive REPL uses the same readline surface as
   // approvals, while MCPClient retains the protocol-level response shape.
   const mcpElicitationClients = [_adhocMcp?.mcpClient, _bundleMcpClient].filter(
@@ -3757,9 +3875,34 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
   // Vim-mode plumbing: capture readline's OWN keypress listeners now so we can
   // suspend them while in NORMAL mode (the engine drives editing then) and
   // reattach them for INSERT mode (readline's rich editing/history/completion).
-  const _rlKeypressListeners = process.stdin.isTTY
+  const _nativeReadlineKeypressListeners = process.stdin.isTTY
     ? process.stdin.listeners("keypress").slice()
     : [];
+  const _consumedReadlineKeypresses = new WeakSet();
+  const _consumeReadlineKeypress = (key) => {
+    if (key && typeof key === "object") _consumedReadlineKeypresses.add(key);
+  };
+  const _rlKeypressListeners = _nativeReadlineKeypressListeners.map(
+    (listener) =>
+      function guardedReadlineKeypress(input, key) {
+        if (
+          key &&
+          typeof key === "object" &&
+          _consumedReadlineKeypresses.has(key)
+        ) {
+          return;
+        }
+        return listener.call(this, input, key);
+      },
+  );
+  if (process.stdin.isTTY) {
+    for (const listener of _nativeReadlineKeypressListeners) {
+      process.stdin.removeListener("keypress", listener);
+    }
+    for (const listener of _rlKeypressListeners) {
+      process.stdin.on("keypress", listener);
+    }
+  }
   const _suspendReadlineKeys = () => {
     for (const l of _rlKeypressListeners)
       process.stdin.removeListener("keypress", l);
@@ -3807,13 +3950,15 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
   // seam (throwIfAborted at each iteration); partial conversation is kept.
   // Idle Esc presses (no active turn) are ignored, and escape-prefixed key
   // sequences (arrows etc.) never reach here as bare "escape".
-  let _turnAbort = null;
+  _turnAbort = null;
   let _lastIdleEscAt = 0;
+  let _replKeypressHandler = null;
   if (process.stdin.isTTY) {
-    process.stdin.on("keypress", (_str, key) => {
+    _replKeypressHandler = (_str, key) => {
       const k = key || {};
       // 1) Turn abort always wins, regardless of vim mode.
       if (k.name === "escape" && !k.meta && _turnAbort) {
+        _consumeReadlineKeypress(key);
         process.stdout.write(chalk.yellow("\n⎋ interrupting…\n"));
         try {
           _turnAbort.abort();
@@ -3849,6 +3994,7 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
       const isShiftTab =
         (k.name === "tab" && k.shift) || k.sequence === "\u001b[Z";
       if (isShiftTab) {
+        _consumeReadlineKeypress(key);
         if (
           _approvalGate &&
           sessionId &&
@@ -3877,14 +4023,30 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
         return;
       }
 
+      // 1.75) Prompt interaction keybindings share the controller used by
+      // slash commands. They are idle-only and stay out of Vim NORMAL mode,
+      // where the modal editor owns every key.
+      if (
+        !_turnAbort &&
+        (!_vimEnabled || !_vim) &&
+        _promptInteractions.handleKeypress(_str, k)
+      ) {
+        _consumeReadlineKeypress(key);
+        return;
+      }
+
       // 2) Vim mode: modal editing on the current input line.
       if (_vimEnabled && !_turnAbort) {
         if (!_vim) {
           // INSERT mode — readline owns the keys; Esc switches to NORMAL.
-          if (k.name === "escape" && !k.meta) _vimEnterNormal();
+          if (k.name === "escape" && !k.meta) {
+            _consumeReadlineKeypress(key);
+            _vimEnterNormal();
+          }
           return;
         }
         // NORMAL mode — readline suspended; the engine interprets every key.
+        _consumeReadlineKeypress(key);
         const res = feedNormalKey(_vim, _str || "", k);
         if (res.submit) {
           // Hand the line to readline as a normal Enter (fires 'line', clears).
@@ -3906,6 +4068,7 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
 
       // 3) Non-vim: double-Esc while idle → rewind picker shortcut.
       if (k.name !== "escape" || k.meta) return;
+      _consumeReadlineKeypress(key);
       const nowTs = Date.now();
       if (nowTs - _lastIdleEscAt < 600) {
         _lastIdleEscAt = 0;
@@ -3930,7 +4093,8 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
       } else {
         _lastIdleEscAt = nowTs;
       }
-    });
+    };
+    process.stdin.prependListener("keypress", _replKeypressHandler);
   }
 
   logger.log(chalk.bold("\nChainlessChain Agent"));
@@ -4007,7 +4171,9 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
         });
         // Custom command wins; otherwise the built-in context-usage render.
         if (_slCfg) {
-          return _sl.renderStatusLine(_slCfg, context, { cwd: process.cwd() });
+          return _sl.renderStatusLine(_slCfg, context, {
+            cwd: process.cwd(),
+          });
         }
         const line = _sl.renderDefaultStatusLine(context);
         return line && line.trim() ? line : null;
@@ -4206,6 +4372,19 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
       return;
     }
 
+    // The interaction commands are registered through the shared registry,
+    // while the mature REPL handlers below remain on their existing direct
+    // paths. --disable-slash-commands replaces `trimmed` with a sentinel, so
+    // it cannot accidentally reach this dispatcher.
+    if (trimmed.startsWith("/")) {
+      const commandName = trimmed.split(/\s+/, 1)[0];
+      if (_promptInteractionSurface.commandNames.has(commandName)) {
+        await _promptInteractionSurface.dispatchSlash(trimmed);
+        prompt();
+        return;
+      }
+    }
+
     if (trimmed === "/help") {
       logger.log(chalk.bold("\nCommands:"));
       logger.log(
@@ -4264,6 +4443,21 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
       logger.log(
         `  ${chalk.cyan("/output-style")} Response persona (/output-style <name|list>; explanatory/learning built-in)`,
       );
+      logger.log(
+        `  ${chalk.cyan("/editor")}     Edit a draft prompt in an external editor`,
+      );
+      logger.log(
+        `  ${chalk.cyan("/stash")}      Stash/list/pop/clear draft prompts`,
+      );
+      logger.log(
+        `  ${chalk.cyan("/recap")}      Show a lightweight session recap`,
+      );
+      logger.log(
+        `  ${chalk.cyan("/suggestions")} Prompt suggestions on|off|status|refresh`,
+      );
+      logger.log(
+        `  ${chalk.cyan("/paste-image")} Attach a clipboard image from a supporting host`,
+      );
       logger.log(
         `  ${chalk.cyan("/config")}     Show config; ${chalk.cyan("/config <key>")} read, ${chalk.cyan("/config <key>=<val>")} set, ${chalk.cyan("/config --help")} keys`,
       );
@@ -4313,7 +4507,7 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
         `  ${chalk.cyan("/add-dir")}    Add an extra working root (/add-dir <dir>; no arg lists roots)`,
       );
       logger.log(
-        `  ${chalk.cyan("/reload-skills")} Re-scan skill layers without restarting`,
+        `  ${chalk.cyan("/reload-skills")} Revoke process Skill grants and re-scan layers`,
       );
       logger.log(
         `  ${chalk.cyan("/reload-plugins")} Re-scan installed plugins after add/trust/upgrade`,
@@ -5173,7 +5367,11 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
               dispatchAsyncHooks(
                 _settingsHooks,
                 "CwdChanged",
-                { old_cwd: oldCwd, cwd: newCwd, session_id: sessionId || null },
+                {
+                  old_cwd: oldCwd,
+                  cwd: newCwd,
+                  session_id: sessionId || null,
+                },
                 { cwd: newCwd, supervisor: _asyncHookSupervisor },
               );
             } catch {
@@ -5737,6 +5935,11 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
     // layers (incl. .claude/skills) without restarting the session.
     if (trimmed === "/reload-skills") {
       try {
+        _replSkillLoader.revokeExecutionAuthorizations?.({
+          message:
+            "Skill execution authorization was revoked by /reload-skills",
+          reasonCode: "reload-skills",
+        });
         _replSkillLoader.clearCache();
         const n = _replSkillLoader.loadAll().length;
         _replBaseSystem = _buildReplBaseSystem();
@@ -5746,7 +5949,7 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
         _persistReplContextSources();
         logger.log(
           chalk.green(
-            `✔ skills reloaded — ${n} available (${_replSkillLoader.getLayerPaths().length} layers re-scanned)`,
+            `✔ Skill grants revoked and skills reloaded — ${n} available (${_replSkillLoader.getLayerPaths().length} layers re-scanned)`,
           ),
         );
       } catch (err) {
@@ -5959,7 +6162,9 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
             logger.log(chalk.gray(l));
         } else {
           // set — createReplGoal throws on a malformed spec (caught below).
-          _sessionGoal = rg.createReplGoal(cmd.spec, { now: () => Date.now() });
+          _sessionGoal = rg.createReplGoal(cmd.spec, {
+            now: () => Date.now(),
+          });
           for (const l of rg.renderGoalStart(_sessionGoal))
             logger.log(chalk.cyan(l));
         }
@@ -7364,6 +7569,35 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
       return;
     }
 
+    // Explicit clipboard attachment chips are consumed only when a real model
+    // turn is about to start. They compose with auto-detected path images and
+    // enter the same provider-neutral multimodal message/vision override.
+    const clipboardImageChips = _promptInteractions.takeClipboardImageChips();
+    const clipboardMerge = mergeClipboardImageChips(
+      _userMessageContent,
+      clipboardImageChips,
+    );
+    if (clipboardMerge.attached > 0) {
+      _userMessageContent = clipboardMerge.content;
+      if (!_visionLlm) {
+        _visionLlm = resolveVisionLlm({
+          hasImage: true,
+          flags: {},
+          llm: {
+            provider,
+            baseUrl,
+            apiKey,
+            visionModel: _visionModel,
+          },
+        });
+      }
+      logger.info(
+        chalk.gray(
+          `[image] ${clipboardMerge.attached} clipboard image(s) attached -> vision model ${_visionLlm.model}`,
+        ),
+      );
+    }
+
     // Add user message (keep the object ref so /note-next can be injected for
     // this turn's model call and then stripped before persistence).
     const _userMsg = { role: "user", content: _userMessageContent };
@@ -7426,7 +7660,17 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
               .map(([k, v]) => `${k}: ${v}`);
             // Append context to the last user message
             const lastMsg = messages[messages.length - 1];
-            lastMsg.content += `\n\n[Context — user provided: ${parts.join(", ")}]`;
+            const slotContext = `[Context - user provided: ${parts.join(", ")}]`;
+            if (Array.isArray(lastMsg.content)) {
+              const textPart = lastMsg.content.find(
+                (part) => part?.type === "text",
+              );
+              if (textPart)
+                textPart.text = `${textPart.text}\n\n${slotContext}`;
+              else lastMsg.content.unshift({ type: "text", text: slotContext });
+            } else {
+              lastMsg.content = `${lastMsg.content}\n\n${slotContext}`;
+            }
             logger.info(chalk.gray(`[slot-fill] ${parts.join(", ")}`));
           }
         }
@@ -7530,22 +7774,29 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
       // reasoning dimmed before it. Skipped (left undefined) in replay mode.
       let _liveStreamed = false;
       let _liveThinkStarted = false;
+      const _settleLiveWrite = (blocked) =>
+        blocked ? _replOutputFlow.wait() : undefined;
       const liveOpts = _streamLive
         ? {
             onToken: (t) => {
               // Separate the answer from the dimmed reasoning above it (once).
-              if (!_liveStreamed && _liveThinkStarted)
-                process.stdout.write("\n");
+              let blocked = false;
+              if (!_liveStreamed && _liveThinkStarted) {
+                blocked = process.stdout.write("\n") === false;
+              }
               _liveStreamed = true;
-              process.stdout.write(t);
+              blocked = process.stdout.write(t) === false || blocked;
+              return _settleLiveWrite(blocked);
             },
             onThinking: (t) => {
               if (process.env.CC_REPL_THINKING === "0") return;
+              let blocked = false;
               if (!_liveThinkStarted) {
                 process.stdout.write(chalk.dim("💭 "));
                 _liveThinkStarted = true;
               }
-              process.stdout.write(chalk.dim(t));
+              blocked = process.stdout.write(chalk.dim(t)) === false || blocked;
+              return _settleLiveWrite(blocked);
             },
           }
         : {};
@@ -7577,7 +7828,9 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
       if (_settingsHooks && !_asyncHookSupervisor) {
         const { AsyncHookSupervisor } =
           await import("../lib/async-hook-supervisor.js");
-        _asyncHookSupervisor = new AsyncHookSupervisor({ persistStats: true });
+        _asyncHookSupervisor = new AsyncHookSupervisor({
+          persistStats: true,
+        });
       }
       const activeMcpRuntime = _activateMcpHostRuntime();
       const activeRawMcpClient = activeMcpRuntime.rawClient || undefined;
@@ -7587,6 +7840,7 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
         thinking: reasoning,
       } = await agentLoop(messages, {
         ...liveOpts,
+        waitForOutput: _replOutputFlow.wait,
         mergeRoles: _mergeRolesThisTurn,
         // Visible auto-retry feedback (Claude-Code 2.1.181): when the model's
         // streaming call hits a transient connection drop and retries, tell the
@@ -7868,6 +8122,15 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
         );
       }
 
+      // Generate follow-up suggestions from the settled assistant turn. The
+      // controller snapshots the actual conversation context and debounces in
+      // the background, so readline and persistence remain non-blocking.
+      const suggestionRun = _promptInteractions.scheduleSuggestions({
+        messages: messages.slice(),
+        lastAssistantText: effectiveResponse || "",
+      });
+      void suggestionRun.promise;
+
       // Auto-save session
       if (sessionId) {
         try {
@@ -8012,6 +8275,7 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
   };
 
   rl.on("line", async (input) => {
+    if (!(await _waitForReplOutput())) return;
     if (_processingLine) {
       const concurrentBtw = _slashCommandsDisabled
         ? null
@@ -8035,10 +8299,12 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
     _processingLine = true;
     try {
       await handleLine(input);
+      if (!(await _waitForReplOutput())) return;
       while (_pendingLines.length) {
         const next = _pendingLines.shift();
         logger.log(chalk.cyan(`▶ running queued input: ${next}`));
         await handleLine(next);
+        if (!(await _waitForReplOutput())) return;
       }
     } finally {
       _processingLine = false;
@@ -8046,6 +8312,18 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
   });
 
   rl.on("close", async () => {
+    if (_replCleanupStarted) return;
+    _replCleanupStarted = true;
+    _replClosing = true;
+    _promptInteractions.dispose();
+    if (process.stdin.isTTY) {
+      if (_replKeypressHandler) {
+        process.stdin.removeListener("keypress", _replKeypressHandler);
+      }
+      for (const listener of _rlKeypressListeners) {
+        process.stdin.removeListener("keypress", listener);
+      }
+    }
     // Leave the alternate screen buffer first so the terminal is restored to
     // the user's scrollback no matter how the REPL exits.
     if (_tuiMode === "fullscreen" && process.stdout.isTTY) {
@@ -8224,6 +8502,31 @@ async function startAgentReplInWorkspace(options = {}, startupAdmission) {
     } catch (_e) {
       // Non-critical
     }
-    process.exit(0);
+    if (!_replOutputFailure) {
+      try {
+        await _replOutputFlow.wait();
+      } catch (error) {
+        _replOutputFailure ||= error;
+      }
+    }
+    const outputExitCode = _replOutputFailure
+      ? _replOutputFailure.code === "EPIPE"
+        ? 0
+        : 1
+      : 0;
+    outputScope.restore();
+    process.exit(outputExitCode);
   });
+  _replCloseReady = true;
+  if (_replClosing) {
+    // stdout may have broken before readline and its cleanup handler were fully
+    // initialized. Close only now so the complete async teardown runs.
+    queueMicrotask(() => {
+      try {
+        rl.close();
+      } catch {
+        process.exitCode = 0;
+      }
+    });
+  }
 }