@cspeach/cli 0.6.0

package/dist/repl/inquirer-guard.js

@@ -0,0 +1,130 @@
+/**
+ * Readline ↔ inquirer hand-off guard.
+ *
+ * Why this exists: repl.tsx runs a long-lived `readline` interface for the
+ * main CSPeach prompt. Tools (`ask_question`, coaching picker, approval
+ * prompt) use `@inquirer/prompts`, which grabs raw stdin for the duration
+ * of the sub-prompt and then releases it. When inquirer releases, the
+ * underlying readline sometimes receives a spurious `close` — we've
+ * observed the CLI drop back to the shell mid-session with no Ctrl-D and
+ * no `/exit`. The safe pattern proven for the coaching picker is:
+ *
+ *   1. set a suppress-close flag so the readline 'close' handler is a no-op
+ *   2. pause() the readline so it doesn't fight inquirer for stdin
+ *   3. run the inquirer prompt
+ *   4. resume() the readline
+ *   5. clear the flag on process.nextTick (readline emits 'close' synchronously
+ *      after release, so we must wait a tick before re-arming)
+ *
+ * This module exposes that pattern as a single `withInquirer(fn)` helper
+ * so tool handlers don't each have to know about the internal readline or
+ * the suppress flag. repl.tsx calls `registerReadline(rl, setSuppress)`
+ * once at startup; tools call `withInquirer(() => input({...}))`.
+ *
+ * When CSPeach runs outside a registered REPL (one-shot mode, tests,
+ * Ink-path entry before registration), `withInquirer` just runs the
+ * function — no pause, no suppress — which is safe because there is no
+ * main readline to disturb.
+ */
+import { clearActiveSpinner } from '../renderer/tool-widget.js';
+let state = null;
+/**
+ * Called by repl.tsx once the main readline is created. The `setSuppress`
+ * callback must flip the same boolean the readline 'close' handler
+ * inspects — otherwise the guard has no effect.
+ */
+export function registerReadline(rl, setSuppress) {
+    state = { rl, setSuppress };
+}
+/** Clear the guard — call when the REPL is shutting down. */
+export function unregisterReadline() {
+    state = null;
+}
+/**
+ * Run `fn` with the main readline paused and its 'close' exit suppressed.
+ * Safe to call when no readline is registered (no-op guard).
+ *
+ * Critical fix 2026-05-01: after inquirer cleanly relinquishes stdin, the
+ * underlying `process.stdin` ends up "unreffed" — paused with no flowing
+ * listener that holds an event-loop ref. The next `rl.question()` call
+ * prints its prompt and then the Node event loop runs out of refs and
+ * exits SILENTLY (no 'close' event, no question rejection — process just
+ * exits). This is what made CSPeach drop back to the shell after every
+ * skill-picker / approval / ask_question prompt.
+ *
+ * Calling `process.stdin.resume()` in the finally re-attaches stdin to
+ * the flowing event-loop ref so the next `rl.question` actually waits.
+ * The ANSI cursor toggle calls inquirer makes during cleanup are what
+ * leave stdin paused; resume() reverses that.
+ */
+export async function withInquirer(fn) {
+    if (!state)
+        return fn();
+    const { rl, setSuppress } = state;
+    // 2026-05-01: silence any active tool-dispatch spinner so it doesn't fight
+    // inquirer for stdout/cursor. The spinner uses \r + erase-line every 80ms,
+    // which collides with inquirer's prompt rendering — visible as ghost-text
+    // and a cursor that hides under the rotating frame while the user types.
+    clearActiveSpinner();
+    // 2026-05-08: snapshot stdin 'data' / 'keypress' listeners BEFORE the
+    // inquirer prompt runs. Some inquirer widgets (notably `search`, used
+    // by /files step 1) strip ALL listeners on cleanup — including
+    // readline's own input handler. Without re-attach, the next
+    // rl.question() shows its prompt with terminal echo on but ignores
+    // Enter (no input handler is wired). Surfaced after Diff 8 stopped
+    // hiding this with an immediate "Goodbye" exit.
+    const beforeData = process.stdin.listeners('data').slice();
+    const beforeKeypress = process.stdin.listeners('keypress').slice();
+    setSuppress(true);
+    rl.pause();
+    // 2026-05-08: explicitly engage raw mode BEFORE the inquirer prompt
+    // renders. Inquirer's select() / search() / input() do this internally
+    // too, but on Windows + post-readline-pause there's a timing window
+    // where the first keystroke arrives in cooked mode and is lost — the
+    // user sees the prompt with `❯ option` already highlighted, presses an
+    // arrow, nothing happens, presses Enter, and only THEN do the arrows
+    // start working (the first Enter flushes the cooked-mode buffer and
+    // hits inquirer's now-armed keypress listener). Live feedback: "for
+    // some reason on this question I have to enter 'enter' first to start
+    // using my arrows". Arming raw mode pre-render closes the window.
+    //
+    // We don't restore in `finally`: inquirer takes its own snapshot of
+    // isRaw at its start (which is now true after our setRawMode call)
+    // and restores TO that value on exit, leaving raw mode on as it
+    // intends — matching what every working "consecutive inquirer prompt"
+    // path already does (e.g. /files step 1 → step 2). rl.resume() in
+    // finally will re-engage readline keypress mode on its own.
+    if (process.stdin.isTTY && !process.stdin.isRaw) {
+        process.stdin.setRawMode(true);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        // Re-attach data / keypress listeners that inquirer removed but
+        // didn't replace. The has() check avoids double-binding any
+        // listener inquirer DID restore (different instance is OK; the
+        // same function reference is the only thing we re-add).
+        const afterData = new Set(process.stdin.listeners('data'));
+        for (const lf of beforeData) {
+            if (!afterData.has(lf)) {
+                process.stdin.on('data', lf);
+            }
+        }
+        const afterKeypress = new Set(process.stdin.listeners('keypress'));
+        for (const lf of beforeKeypress) {
+            if (!afterKeypress.has(lf)) {
+                process.stdin.on('keypress', lf);
+            }
+        }
+        // Order matters here:
+        //  1. resume stdin so the event loop stays referenced (otherwise the
+        //     next rl.question prints its prompt and the process exits).
+        //  2. resume the readline so it accepts new input.
+        //  3. defer the suppress-clear so the spurious 'close' that inquirer
+        //     synchronously emits on release is still ignored.
+        process.stdin.resume();
+        rl.resume();
+        process.nextTick(() => setSuppress(false));
+    }
+}

package/dist/repl/inquirer-theme.js

@@ -0,0 +1,41 @@
+/**
+ * Shared @inquirer/prompts theme. Centralises CSPeach's color discipline
+ * so any prompt — select, input, confirm, password, checkbox — looks the
+ * same and stays in line with the surrounding terminal aesthetic.
+ *
+ * Why this exists: by default @inquirer/prompts renders the chosen
+ * answer in cyan. CC-style discipline says color should encode meaning
+ * (success / error / brand) — a cyan answer line on every prompt
+ * trains the user to treat color as decoration. Override the answer
+ * style to default white so the only colored thing on a finished
+ * prompt is the leading green ✔ check.
+ *
+ * 2026-05-01 (CC-parity color audit): introduced as part of the cuts
+ * after screenshot review showed 9 distinct hues on a single screen.
+ * Goal is to land at ~5: default, dim, brand peach, green outcome,
+ * red error.
+ */
+import chalk from 'chalk';
+/** The shared theme. Pass as `theme` to any @inquirer/prompts call. */
+export const inquirerTheme = {
+    style: {
+        /**
+         * The selected answer printed back after Enter — by default cyan,
+         * here default-color. The leading ✔ (provided by inquirer) stays
+         * green to encode "done", which is enough signal on its own.
+         */
+        answer: (s) => chalk.white(s),
+        /**
+         * Help / hint text shown next to the prompt question. Default
+         * inquirer hint is dim — keep it dim, just be explicit so future
+         * inquirer version bumps don't regress us.
+         */
+        help: (s) => chalk.dim(s),
+        /**
+         * Highlighted (cursor-on) choice in select / checkbox. Default is
+         * cyan. Use a subtle inverse instead — the cursor `❯` glyph is
+         * the primary signal anyway.
+         */
+        highlight: (s) => chalk.bold(s),
+    },
+};

package/dist/repl/rule8-detector.js

@@ -0,0 +1,99 @@
+/**
+ * Rule 8 — no batch without plan. Per-LLM-turn write-op counter.
+ *
+ * One CSPeach LLM turn = one user prompt processed end-to-end through the
+ * agent loop, ending when the assistant's stop_reason is end_turn or
+ * max_tokens. Many Anthropic API calls and tool dispatches happen within
+ * a single turn — the boundary is the user prompt, NOT the API call.
+ *
+ * Reset at turn start in agent/loop.ts (top of runTurn, before the API loop).
+ * Gate fires from agent/tool-dispatch.ts (where LLM-issued tool calls land).
+ *
+ * The 1st mutating call of a turn proceeds WITHOUT the Rule-8 prompt — only
+ * increments the counter. The 2nd (and any subsequent) mutating call fires
+ * the RULE_8_BATCH_PLAN confirmation prompt. Independent of /safety-mode —
+ * batch detection is unconditional per Plan 3 §6.6.
+ *
+ * Module-scope singleton per CLI process. Tests must call resetRule8State()
+ * in beforeEach to avoid leakage across Vitest test files.
+ */
+let writeOpsThisTurn = [];
+let planGateApprovedThisTurn = false;
+/**
+ * Record a successful mutating tool dispatch. Called from tool-dispatch
+ * AFTER tool.handler returns without is_error.
+ */
+export function recordWriteOp(tool, args) {
+    writeOpsThisTurn.push({ tool, args, ts: new Date().toISOString() });
+}
+/**
+ * Returns true on the 2nd (and later) mutating call of the turn — the gate
+ * fires here. The 1st mutating call proceeds without the prompt; only its
+ * recordWriteOp pushes the seed entry.
+ *
+ * 2026-05-01: when the user already approved a batch via the plan-gate
+ * (request_approval → "Apply all" or per-change "Apply" for all changes),
+ * Rule 8 is redundant — they've seen the full plan and explicitly approved
+ * every operation in it. Suppress in that case. Rule 8 remains active for
+ * batches the model issues OUTSIDE the approval flow (rare but possible —
+ * e.g. recovery paths, ad-hoc tool calls), so the safety net stays.
+ */
+export function shouldGateRule8() {
+    if (planGateApprovedThisTurn)
+        return false;
+    return writeOpsThisTurn.length >= 1;
+}
+/**
+ * Tell the Rule 8 gate that the plan-gate has already covered this turn's
+ * batch. Called from request_approval when the user picks "Apply all" or
+ * approves every change individually. Reset by resetRule8State at the
+ * start of the next turn.
+ */
+export function markPlanGateApproved() {
+    planGateApprovedThisTurn = true;
+}
+/**
+ * Reset state at the start of every LLM turn. Called from runTurn before
+ * the agent loop begins.
+ */
+export function resetRule8State() {
+    writeOpsThisTurn = [];
+    planGateApprovedThisTurn = false;
+}
+/**
+ * Read-only view of the writes that have already happened this turn. Used
+ * by renderPlanSummary and by tests.
+ */
+export function getWriteOpsThisTurn() {
+    return writeOpsThisTurn;
+}
+/**
+ * Render a short human-readable plan summary used in the SafetyAction
+ * what_will_happen field for RULE_8_BATCH_PLAN. Lists prior writes + the
+ * proposed-next write.
+ */
+export function renderPlanSummary(proposedNext) {
+    const lines = [];
+    lines.push(`Batch in progress (${writeOpsThisTurn.length + 1} write ops this turn):`);
+    writeOpsThisTurn.forEach((op, i) => {
+        lines.push(`  ${i + 1}. ${op.tool} ${summarizeArgs(op.args)}`);
+    });
+    lines.push(`  ${writeOpsThisTurn.length + 1}. ${proposedNext.tool} ${summarizeArgs(proposedNext.args)} ← about to dispatch`);
+    return lines.join('\n');
+}
+function summarizeArgs(args) {
+    // Best-effort one-line summary. Pulls the most useful identifier fields:
+    // type+name, class_name+method_name, transport.
+    const a = args;
+    const parts = [];
+    if (typeof a['type'] === 'string' && typeof a['name'] === 'string') {
+        parts.push(`${a['type']} ${a['name']}`);
+    }
+    if (typeof a['class_name'] === 'string' && typeof a['method_name'] === 'string') {
+        parts.push(`${a['class_name']}->${a['method_name']}`);
+    }
+    if (typeof a['transport'] === 'string' && a['transport']) {
+        parts.push(`(transport: ${a['transport']})`);
+    }
+    return parts.length === 0 ? '(no key args)' : parts.join(' ');
+}

package/dist/repl/safety-confirm.js

@@ -0,0 +1,106 @@
+/**
+ * Safety-confirm-as-mode: structured confirmation cards for Forge Rule
+ * triggers (Rules 7 / 7a / 8 / 9 / 10). Promotes the safety prompts from
+ * ad-hoc to a first-class mode. When this is the active confirmation
+ * surface, every rule-triggering operation gets a card showing which rule
+ * applies, what's about to happen, and what rollback is available.
+ *
+ * Pure orchestration over `@inquirer/prompts.confirm` — no I/O of its own
+ * beyond the prompt invocation.
+ */
+import chalk from 'chalk';
+import { select } from '@inquirer/prompts';
+import { withInquirer } from './inquirer-guard.js';
+import { inquirerTheme } from './inquirer-theme.js';
+const RULE_LABEL = {
+    RULE_7_SNAPSHOT_BEFORE_WRITE: 'RULE 7 — snapshot before write',
+    RULE_7A_USE_UPDATE_METHOD: 'RULE 7a — use sap_update_method (not sap_set_source)',
+    RULE_8_BATCH_PLAN: 'RULE 8 — no batch without plan',
+    RULE_9_TRANSPORT_RELEASE: 'RULE 9 — transport release (irreversible)',
+    RULE_9_TRANSPORT_ISOLATION: 'RULE 9 — transport isolation',
+    RULE_10_VERIFY_AFTER_WRITE: 'RULE 10 — verify after write',
+};
+export async function presentSafetyConfirmation(action) {
+    const card = renderCard(action);
+    // 2026-05-01: switched from confirm() to select() to fix the "press Enter
+    // first, then 'y'" race observed in dispatched-tool rule-8 prompts. confirm
+    // has a brief window after rendering its multi-line message before raw
+    // mode engages, during which the first keystroke can land in cooked-mode
+    // readline instead of inquirer (visible as a stray 'y' echoed below the
+    // prompt). select needs arrow keys, so it engages raw mode aggressively
+    // and consistently — and it matches the Apply/Review/Cancel pattern the
+    // approval gauntlet already uses, so the UX stays uniform across all gates.
+    const first = await withInquirer(() => select({
+        message: card,
+        default: 'apply',
+        theme: inquirerTheme,
+        choices: [
+            { value: 'apply', name: 'Apply' },
+            { value: 'cancel', name: 'Cancel' },
+        ],
+    }));
+    if (first === 'cancel') {
+        return { confirmed: false, reason: 'user declined first prompt' };
+    }
+    // RULE 9 transport-release is irreversible — require a second explicit ack.
+    if (action.rule === 'RULE_9_TRANSPORT_RELEASE') {
+        const second = await withInquirer(() => select({
+            message: `IRREVERSIBLE — releasing ${action.transport} cannot be undone from this side. ` +
+                `Are you absolutely sure?`,
+            default: 'cancel',
+            theme: inquirerTheme,
+            choices: [
+                { value: 'cancel', name: 'Cancel' },
+                { value: 'release', name: 'Release transport' },
+            ],
+        }));
+        if (second === 'cancel') {
+            return { confirmed: false, reason: 'user declined irreversibility ack' };
+        }
+    }
+    return { confirmed: true };
+}
+/**
+ * Minimal indented summary block — replaces the chunky ASCII-art box.
+ * Renders as:
+ *
+ *   ⚠  RULE 8 — no batch without plan
+ *      op:        sap_set_source
+ *      object:    PROG ZTEST_FIXED_2
+ *      transport: (none)
+ *      batch:     2 objects this turn
+ *      what:      Batch in progress (...)
+ *      rollback:  available (snapshot)
+ *
+ * The `⚠` glyph is yellow (alert) — distinct from peach (brand) and red
+ * (error) so the user immediately recognises a Forge Rule prompt. Body
+ * lines are indented under the header for visual grouping without a box.
+ */
+function renderCard(action) {
+    const lines = [];
+    const transport = action.transport && action.transport.length > 0 ? action.transport : '(none)';
+    const rollback = action.rollback_available ? 'available (snapshot)' : chalk.red('NOT available');
+    lines.push('');
+    lines.push(`${chalk.yellow('⚠')}  ${chalk.yellow.bold(RULE_LABEL[action.rule])}`);
+    lines.push(`   ${chalk.dim('op:       ')} ${action.op}`);
+    lines.push(`   ${chalk.dim('object:   ')} ${action.object.type} ${action.object.name}`);
+    lines.push(`   ${chalk.dim('transport:')} ${transport}`);
+    if (action.rule === 'RULE_8_BATCH_PLAN' && typeof action.batch_count === 'number') {
+        lines.push(`   ${chalk.dim('batch:    ')} ${action.batch_count} objects this turn`);
+    }
+    // what_will_happen may include embedded newlines (e.g. Rule 8 plan summary).
+    // Indent the continuation lines so they align under the header field.
+    const whatLines = action.what_will_happen.split('\n');
+    if (whatLines.length === 1) {
+        lines.push(`   ${chalk.dim('what:     ')} ${whatLines[0]}`);
+    }
+    else {
+        lines.push(`   ${chalk.dim('what:     ')} ${whatLines[0]}`);
+        for (let i = 1; i < whatLines.length; i++) {
+            lines.push(`              ${whatLines[i]}`);
+        }
+    }
+    lines.push(`   ${chalk.dim('rollback: ')} ${rollback}`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/repl/safety-mode-state.js

@@ -0,0 +1,36 @@
+/**
+ * Module-scope state for the safety-confirm-as-mode toggle. The REPL turns
+ * this on via `--safety-confirm` flag at start, or `/safety-mode on|off` at
+ * runtime. Tool dispatchers that hit a Forge Rule (snapshot, write, batch,
+ * transport release, activation) read isSafetyConfirmEnabled() and choose
+ * presentSafetyConfirmation() vs the legacy ad-hoc inquirer prompt.
+ *
+ * Module-scope state instead of a context-passed flag because the toggle is
+ * orthogonal to call sites — every dispatch site needs to read it without
+ * changing every signature in the call chain. Keep the state here, keep the
+ * accessors small, and keep the test surface tiny.
+ */
+let enabled = false;
+export function isSafetyConfirmEnabled() {
+    return enabled;
+}
+export function setSafetyConfirmEnabled(value) {
+    enabled = Boolean(value);
+}
+/**
+ * Handles the `/safety-mode on` / `/safety-mode off` slash command. Returns
+ * a human-readable status string for the REPL to print. Unknown args fall
+ * through to a status-only response without changing state.
+ */
+export function handleSafetyModeCommand(args) {
+    const arg = args.trim().toLowerCase();
+    if (arg === 'on') {
+        setSafetyConfirmEnabled(true);
+        return 'Safety-confirm mode: ON. Forge Rule 7/7a/8/9/10 ops now show structured confirmation cards.';
+    }
+    if (arg === 'off') {
+        setSafetyConfirmEnabled(false);
+        return 'Safety-confirm mode: OFF. Falling back to ad-hoc prompts.';
+    }
+    return `Safety-confirm mode is currently ${enabled ? 'ON' : 'OFF'}. Use \`/safety-mode on\` or \`/safety-mode off\`.`;
+}

package/dist/repl/slash-completer.js

@@ -0,0 +1,59 @@
+/**
+ * Slash-command Tab completion for the REPL readline.
+ *
+ * UX contract:
+ *   - User types `/` then Tab → list of every available command (skills +
+ *     built-ins) printed below the prompt; line stays untouched.
+ *   - User types `/abap-r` then Tab → if 1 match, line auto-completes.
+ *     If multiple, list filtered matches; line stays.
+ *   - User types non-slash text + Tab → no completion (no spurious matches).
+ *
+ * Backed by readline's native `completer` option, so it inherits the
+ * prompt's history-aware redraw and works without a custom render loop.
+ */
+import { SKILL_CATALOG } from '../skill-catalog.js';
+/**
+ * Built-in slash commands that are NOT skill routes (these are handled
+ * directly by the REPL's command dispatcher, not by the agent loop).
+ * Keep this list aligned with the `if (trimmed === '/...')` branches in
+ * repl.tsx so Tab doesn't suggest commands that don't exist.
+ */
+const BUILTIN_COMMANDS = [
+    '/cancel',
+    '/exit',
+    '/quit',
+    '/help',
+    '/skills',
+    '/new',
+    '/reset',
+    '/ui',
+    '/reroute',
+    '/transport',
+];
+/**
+ * Build the full slash-command list once at module load. Skill commands
+ * come from SKILL_CATALOG so adding a skill there auto-extends Tab.
+ */
+function buildAllCommands() {
+    const skillCmds = SKILL_CATALOG.map((s) => `/${s.name}`);
+    return [...BUILTIN_COMMANDS, ...skillCmds].sort();
+}
+const ALL_COMMANDS = buildAllCommands();
+/**
+ * readline `completer` callback. Returns `[hits, prefix]` per Node's
+ * contract:
+ *   - hits: matching completion strings (full lines, not deltas)
+ *   - prefix: the substring of `line` that the hits should replace
+ *
+ * Behavior:
+ *   - line empty                  → []
+ *   - line doesn't start with /   → [] (no-op for natural prose)
+ *   - line === '/'                → all commands
+ *   - line === '/abap-'           → all skills under that prefix
+ */
+export function slashCompleter(line) {
+    if (!line.startsWith('/'))
+        return [[], line];
+    const hits = ALL_COMMANDS.filter((c) => c.startsWith(line));
+    return [hits, line];
+}

package/dist/repl/slash-picker.js

@@ -0,0 +1,124 @@
+/**
+ * Slash-command live picker. Opens an @inquirer/prompts `search` prompt
+ * pre-filtered to whatever the user has typed so far after the slash, lets
+ * them refine the filter character-by-character, navigate with arrow
+ * keys, and confirm with Enter. Replaces the Tab-cycle autocomplete.
+ *
+ * UX contract:
+ *   - User types `/` then Enter        → picker shows ALL commands
+ *   - User types `/abap-r` then Enter  → picker pre-filtered to those
+ *     commands matching `abap-r`. User can refine further or pick.
+ *   - User types `/abap-refactor` and presses Enter → exact match, no
+ *     picker opens (the existing routing handles the slash directly).
+ *   - User cancels (Esc / Ctrl-C inside picker) → returns null; caller
+ *     treats the original line as cancelled.
+ *
+ * Layout-friendly: renders below the prompt via inquirer's normal
+ * full-screen takeover, then erases itself on Enter or Esc — same
+ * mechanism as every other inquirer prompt in the REPL, so it
+ * coexists with the readline / withInquirer guard.
+ */
+import { search } from '@inquirer/prompts';
+import { withInquirer } from './inquirer-guard.js';
+import { inquirerTheme } from './inquirer-theme.js';
+import { SKILL_CATALOG } from '../skill-catalog.js';
+const BUILTIN_ENTRIES = [
+    { name: '/cancel', description: 'Cancel the current pre-filled command, return to a clean prompt' },
+    { name: '/exit', description: 'Exit CSPeach' },
+    { name: '/quit', description: 'Exit CSPeach (alias)' },
+    { name: '/help', description: 'Show all skills and commands' },
+    { name: '/skills', description: 'Show all skills (alias)' },
+    { name: '/new', description: 'Reset routing — next prompt is classified afresh' },
+    { name: '/reset', description: 'Reset routing (alias)' },
+    { name: '/ui', description: 'View or change rendering mode (auto / ink / classic)' },
+    { name: '/reroute', description: 'Re-dispatch the previous prompt to a different skill' },
+    { name: '/transport', description: 'View or set the active transport for this session' },
+];
+function buildCatalogue() {
+    const skillEntries = SKILL_CATALOG.map((s) => ({
+        name: `/${s.name}`,
+        description: s.description,
+    }));
+    return [...BUILTIN_ENTRIES, ...skillEntries].sort((a, b) => a.name.localeCompare(b.name));
+}
+const ALL_ENTRIES = buildCatalogue();
+/**
+ * Open the slash picker. Returns the picked command WITHOUT a leading
+ * slash (caller is expected to construct the full prompt) or null if
+ * the user cancelled.
+ *
+ * @param prefix  characters typed AFTER the slash (e.g. 'abap-r' for
+ *                input '/abap-r'). Used to pre-filter the catalogue
+ *                so the user doesn't need to retype what they had.
+ */
+export async function openSlashPicker(prefix) {
+    // Pre-filter the catalogue to entries whose command name (without slash)
+    // contains the typed prefix as a substring — substring rather than
+    // startsWith because users often remember a fragment in the middle of
+    // a name (e.g. 'fix' should bring up /abap-atc-fix and /abap-upgrade-fix).
+    const lowerPrefix = prefix.trim().toLowerCase();
+    const seeded = lowerPrefix.length === 0
+        ? ALL_ENTRIES
+        : ALL_ENTRIES.filter((e) => e.name.toLowerCase().includes(lowerPrefix));
+    // If the prefix narrows down to exactly one command, just return it
+    // without opening a picker — saves the user a keystroke.
+    if (seeded.length === 1) {
+        return seeded[0].name.slice(1); // strip leading slash
+    }
+    // If the prefix narrows to zero commands, fall back to ALL entries so
+    // the user has something to pick from rather than an empty list.
+    const choicesForPicker = seeded.length === 0 ? ALL_ENTRIES : seeded;
+    // 2026-05-01: explicit cancel sentinel. @inquirer/prompts.search does
+    // NOT bind Esc to cancellation — only Ctrl+C does, and many users
+    // won't think to use it (and on some terminals Ctrl+C kills the
+    // whole process). Make cancel a first-class choice the user can
+    // arrow up to and press Enter on.
+    const CANCEL_VALUE = '__cspeach_cancel__';
+    try {
+        const picked = await withInquirer(() => search({
+            message: 'Pick a command',
+            theme: inquirerTheme,
+            source: async (input) => {
+                const filter = (input ?? '').toLowerCase();
+                const filtered = filter.length === 0
+                    ? choicesForPicker
+                    : choicesForPicker.filter((e) => e.name.toLowerCase().includes(filter));
+                // Cancel sentinel is always available regardless of filter,
+                // so a typo can't trap the user inside the picker.
+                const cancelChoice = {
+                    name: '← Cancel — keep my typed text and let me edit it',
+                    value: CANCEL_VALUE,
+                    short: 'cancel',
+                };
+                const choices = filtered.map((e) => ({
+                    name: `${e.name.padEnd(28)} ${e.description}`,
+                    value: e.name,
+                    short: e.name,
+                }));
+                return [cancelChoice, ...choices];
+            },
+        }));
+        if (picked === CANCEL_VALUE)
+            return null;
+        return typeof picked === 'string' ? picked.slice(1) : null; // strip leading slash
+    }
+    catch {
+        // Ctrl+C inside the picker — treat as cancellation.
+        return null;
+    }
+}
+/**
+ * Quick check: does the typed line match a real, registered slash
+ * command exactly? Used by the REPL to decide between "pass through to
+ * existing routing" and "open picker for ambiguous input".
+ *
+ * The match is on the command name only; arguments after the command
+ * (e.g. `/transport S4HK903361`) are ignored — `/transport` itself is
+ * registered, so the line should pass through.
+ */
+export function isExactSlashMatch(trimmed) {
+    if (!trimmed.startsWith('/'))
+        return false;
+    const head = trimmed.split(/\s+/, 1)[0].toLowerCase();
+    return ALL_ENTRIES.some((e) => e.name === head);
+}

package/dist/repl/update-method-preview-hook.js

@@ -0,0 +1,45 @@
+/**
+ * PreviewHook factories for sap_update_method diff-confirmation gate.
+ *
+ * Three factories cover the three execution contexts:
+ *   - replPreviewHook       — interactive REPL: renders diff + asks confirm
+ *   - noopPreviewHook       — auto-confirm (reserved for trusted paths)
+ *   - alwaysDeclinePreviewHook — refuse every confirm (one-shot / non-interactive)
+ *
+ * B.0a plumbing: factories are wired into ToolContext.previewHook at all 5
+ * construction sites. B.1 will consume ctx.previewHook inside sap_update_method.
+ */
+import { confirm } from '@inquirer/prompts';
+import { renderDiff } from './diff-display.js';
+import { withInquirer } from './inquirer-guard.js';
+/**
+ * B.1 real interactive hook — composes renderDiff + @inquirer/prompts.confirm.
+ * Renders a unified diff inside the REPL and asks the user "Apply change?".
+ */
+export const replPreviewHook = async ({ className, methodName, currentBody, proposedBody, }) => {
+    const diff = renderDiff(currentBody, proposedBody, {
+        label: `${className}->${methodName}`,
+        syntaxHighlight: true,
+    });
+    process.stdout.write(`\n${diff}\n`);
+    const confirmed = await withInquirer(() => confirm({
+        message: `Apply change to ${className}->${methodName}?`,
+        default: false,
+    }));
+    return { confirmed };
+};
+/**
+ * No-op hook — confirms automatically without prompting. Use for paths where we
+ * trust the LLM (classifier; doctor probe-write where the developer initiated
+ * the run). NOT used in current dispatch sites — exported for future flexibility.
+ */
+export const noopPreviewHook = async () => ({ confirmed: true });
+/**
+ * Always-decline hook — refuses every confirmation. Use for non-interactive
+ * paths where there is no human to confirm (one-shot, scripts). Writes that
+ * need diff confirmation fail safely with `cancelled_by_user` instead of
+ * silently going through.
+ */
+export const alwaysDeclinePreviewHook = async () => ({
+    confirmed: false,
+});