reasonix 0.6.0 → 0.7.1

package/dist/index.js

@@ -334,7 +334,7 @@ async function harvest(reasoningContent, client, options = {}, signal) {
   const minLen = options.minReasoningLen ?? 40;
   const trimmed = reasoningContent.trim();
   if (trimmed.length < minLen) return emptyPlanState();
-  const model = options.model ?? "deepseek-chat";
+  const model = options.model ?? "deepseek-v4-flash";
   const maxItems = options.maxItems ?? 5;
   const maxItemLen = options.maxItemLen ?? 80;
   const system = SYSTEM_PROMPT.replace("{maxItems}", String(maxItems)).replace(
@@ -1729,8 +1729,9 @@ var ARGS_COMPACT_THRESHOLD_TOKENS = 800;
 var TURN_END_RESULT_CAP_TOKENS = 3e3;
 var FAILURE_ESCALATION_THRESHOLD = 3;
 var ESCALATION_MODEL = "deepseek-v4-pro";
-var NEEDS_PRO_MARKER = "<<<NEEDS_PRO>>>";
-var NEEDS_PRO_BUFFER_CHARS = 80;
+var NEEDS_PRO_MARKER_PREFIX = "<<<NEEDS_PRO";
+var NEEDS_PRO_MARKER_RE = /^<<<NEEDS_PRO(?::\s*([^>]*))?>>>/;
+var NEEDS_PRO_BUFFER_CHARS = 256;
 var CacheFirstLoop = class {
   client;
   prefix;
@@ -1796,6 +1797,14 @@ var CacheFirstLoop = class {
    * the user doesn't watch flash retry the same edit 5 times.
    */
   _turnFailureCount = 0;
+  /**
+   * Per-type breakdown of failure signals counted toward the turn's
+   * auto-escalation threshold. Surfaced in the warning when the
+   * threshold trips so the user sees what kind of trouble flash
+   * actually hit ("3× search-mismatch, 2× truncated") rather than
+   * just a bare count. Reset alongside _turnFailureCount.
+   */
+  _turnFailureTypes = {};
   constructor(opts) {
     this.client = opts.client;
     this.prefix = opts.prefix;
@@ -1823,10 +1832,11 @@ var CacheFirstLoop = class {
     this.sessionName = opts.session ?? null;
     if (this.sessionName) {
       const prior = loadSessionMessages(this.sessionName);
-      const { messages, healedCount, tokensSaved } = healLoadedMessagesByTokens(
-        prior,
-        DEFAULT_MAX_RESULT_TOKENS
-      );
+      const shrunk = healLoadedMessagesByTokens(prior, DEFAULT_MAX_RESULT_TOKENS);
+      const stamped = stampMissingReasoningForThinkingMode(shrunk.messages, this.model);
+      const messages = stamped.messages;
+      const healedCount = shrunk.healedCount + stamped.stampedCount;
+      const tokensSaved = shrunk.tokensSaved;
       for (const msg of messages) this.log.append(msg);
       this.resumedMessageCount = messages.length;
       if (healedCount > 0) {
@@ -2053,15 +2063,41 @@ var CacheFirstLoop = class {
     return this._escalateThisTurn ? ESCALATION_MODEL : this.model;
   }
   /**
-   * True when the assistant's content is a self-reported escalation
-   * request. Only the FIRST line matters — the model is instructed
-   * to emit the marker as the first output token if at all. Matching
-   * anywhere else in the text is a normal content reference (e.g.
-   * the user asked about the marker itself, or prose that happens
-   * to contain angle-brackets).
+   * Parse the escalation marker out of the model's leading content.
+   * Returns `{ matched: true, reason? }` for both bare and reason-
+   * carrying forms. Only the FIRST line matters — the model is
+   * instructed to emit the marker as the first output token if at
+   * all. Matches anywhere else in the text are normal content
+   * references (e.g. the user asked about the marker itself).
    */
+  parseEscalationMarker(content) {
+    const m = NEEDS_PRO_MARKER_RE.exec(content.trimStart());
+    if (!m) return { matched: false };
+    const reason = m[1]?.trim();
+    return { matched: true, reason: reason || void 0 };
+  }
+  /** Convenience boolean — same gate the streaming path used to call. */
   isEscalationRequest(content) {
-    return content.trimStart().startsWith(NEEDS_PRO_MARKER);
+    return this.parseEscalationMarker(content).matched;
+  }
+  /**
+   * Could `buf` STILL plausibly become the full marker as more chunks
+   * arrive? Drives the streaming buffer's flush decision: while this
+   * is true we keep accumulating; once it's false (or the buffer
+   * exceeds the byte limit) we flush so the user isn't staring at a
+   * delayed display for arbitrary content that just happens to start
+   * with `<`.
+   */
+  looksLikePartialEscalationMarker(buf) {
+    const t = buf.trimStart();
+    if (t.length === 0) return true;
+    if (t.length <= NEEDS_PRO_MARKER_PREFIX.length) {
+      return NEEDS_PRO_MARKER_PREFIX.startsWith(t);
+    }
+    if (!t.startsWith(NEEDS_PRO_MARKER_PREFIX)) return false;
+    const rest = t.slice(NEEDS_PRO_MARKER_PREFIX.length);
+    if (rest[0] !== ">" && rest[0] !== ":") return false;
+    return true;
   }
   /**
    * Check whether a tool result string looks like a "flash struggled"
@@ -2075,16 +2111,18 @@ var CacheFirstLoop = class {
    */
   noteToolFailureSignal(resultJson, repair) {
     let bumped = false;
-    if (resultJson.includes('"error"') && resultJson.includes("search text not found")) {
-      this._turnFailureCount += 1;
+    const bump = (kind, by = 1) => {
+      this._turnFailureCount += by;
+      this._turnFailureTypes[kind] = (this._turnFailureTypes[kind] ?? 0) + by;
       bumped = true;
+    };
+    if (resultJson.includes('"error"') && resultJson.includes("search text not found")) {
+      bump("search-mismatch");
     }
     if (repair) {
-      const repairs = repair.scavenged + repair.truncationsFixed + repair.stormsBroken;
-      if (repairs > 0) {
-        this._turnFailureCount += repairs;
-        bumped = true;
-      }
+      if (repair.scavenged > 0) bump("scavenged", repair.scavenged);
+      if (repair.truncationsFixed > 0) bump("truncated", repair.truncationsFixed);
+      if (repair.stormsBroken > 0) bump("storm-broken", repair.stormsBroken);
     }
     if (bumped && !this._escalateThisTurn && this._turnFailureCount >= FAILURE_ESCALATION_THRESHOLD) {
       this._escalateThisTurn = true;
@@ -2092,6 +2130,16 @@ var CacheFirstLoop = class {
     }
     return false;
   }
+  /**
+   * Render `_turnFailureTypes` as a comma-separated breakdown like
+   * "2× search-mismatch, 1× truncated" for the auto-escalation
+   * warning. Empty if no types have been recorded yet (defensive —
+   * the warning sites only call this after a bump).
+   */
+  formatFailureBreakdown() {
+    const parts = Object.entries(this._turnFailureTypes).filter(([, n]) => n > 0).map(([kind, n]) => `${n}\xD7 ${kind}`);
+    return parts.length > 0 ? parts.join(", ") : `${this._turnFailureCount} repair/error signal(s)`;
+  }
   buildMessages(pendingUser) {
     const healed = healLoadedMessages(this.log.toMessages(), DEFAULT_MAX_RESULT_CHARS);
     const msgs = [...this.prefix.toMessages(), ...healed.messages];
@@ -2147,6 +2195,7 @@ var CacheFirstLoop = class {
     this.scratch.reset();
     this.repair.resetStorm();
     this._turnFailureCount = 0;
+    this._turnFailureTypes = {};
     this._escalateThisTurn = false;
     let armedConsumed = false;
     if (this._proArmedForNextTurn) {
@@ -2335,7 +2384,7 @@ var CacheFirstLoop = class {
                 if (this.isEscalationRequest(escalationBuf)) {
                   break;
                 }
-                if (escalationBuf.length >= NEEDS_PRO_BUFFER_CHARS || escalationBuf.includes("\n")) {
+                if (escalationBuf.length >= NEEDS_PRO_BUFFER_CHARS || !this.looksLikePartialEscalationMarker(escalationBuf)) {
                   escalationBufFlushed = true;
                   yield {
                     turn: this._turn,
@@ -2430,11 +2479,13 @@ var CacheFirstLoop = class {
         return;
       }
       if (this.modelForCurrentCall() !== ESCALATION_MODEL && this.isEscalationRequest(assistantContent)) {
+        const { reason } = this.parseEscalationMarker(assistantContent);
         this._escalateThisTurn = true;
+        const reasonSuffix = reason ? ` \u2014 ${reason}` : "";
         yield {
           turn: this._turn,
           role: "warning",
-          content: `\u21E7 flash requested escalation \u2014 retrying this turn on ${ESCALATION_MODEL}`
+          content: `\u21E7 flash requested escalation \u2014 retrying this turn on ${ESCALATION_MODEL}${reasonSuffix}`
         };
         assistantContent = "";
         reasoningContent = "";
@@ -2469,7 +2520,12 @@ var CacheFirstLoop = class {
         assistantContent || null
       );
       this.appendAndPersist(
-        this.assistantMessage(assistantContent, repairedCalls, reasoningContent)
+        this.assistantMessage(
+          assistantContent,
+          repairedCalls,
+          this.modelForCurrentCall(),
+          reasoningContent
+        )
       );
       yield {
         turn: this._turn,
@@ -2484,7 +2540,7 @@ var CacheFirstLoop = class {
         yield {
           turn: this._turn,
           role: "warning",
-          content: `\u21E7 auto-escalating to ${ESCALATION_MODEL} for the rest of this turn \u2014 flash hit ${this._turnFailureCount} repair/error signals. Next turn falls back to ${this.model} unless /pro is armed.`
+          content: `\u21E7 auto-escalating to ${ESCALATION_MODEL} for the rest of this turn \u2014 flash hit ${this.formatFailureBreakdown()}. Next turn falls back to ${this.model} unless /pro is armed.`
         };
       }
       if (report.stormsBroken > 0) {
@@ -2498,6 +2554,11 @@ var CacheFirstLoop = class {
         };
       }
       if (repairedCalls.length === 0) {
+        const allSuppressed = report.stormsBroken > 0 && toolCalls.length > 0;
+        if (allSuppressed) {
+          yield* this.forceSummaryAfterIterLimit({ reason: "stuck" });
+          return;
+        }
         this.autoCompactToolResultsOnTurnEnd();
         yield { turn: this._turn, role: "done", content: assistantContent };
         return;
@@ -2608,7 +2669,7 @@ ${reason}`;
           yield {
             turn: this._turn,
             role: "warning",
-            content: `\u21E7 auto-escalating to ${ESCALATION_MODEL} for the rest of this turn \u2014 flash hit ${this._turnFailureCount} edit failure(s). Next turn falls back to ${this.model} unless /pro is armed.`
+            content: `\u21E7 auto-escalating to ${ESCALATION_MODEL} for the rest of this turn \u2014 flash hit ${this.formatFailureBreakdown()}. Next turn falls back to ${this.model} unless /pro is armed.`
           };
         }
         yield {
@@ -2652,7 +2713,9 @@ ${reason}`;
 
 ${summary}`;
       const summaryStats = this.stats.record(this._turn, summaryModel, resp.usage ?? new Usage());
-      this.appendAndPersist(this.assistantMessage(summary, [], resp.reasoningContent ?? void 0));
+      this.appendAndPersist(
+        this.assistantMessage(summary, [], summaryModel, resp.reasoningContent)
+      );
       yield {
         turn: this._turn,
         role: "assistant_final",
@@ -2683,28 +2746,39 @@ ${summary}`;
     }
     return final;
   }
-  assistantMessage(content, toolCalls, reasoningContent) {
+  /**
+   * Build an assistant message for the log. The `producingModel` arg is
+   * the model that actually generated this turn (flash, pro, the
+   * forced-summary flash call, `this.model` for synthetics, etc.) —
+   * NOT `this.model`, because escalation + forced-summary can both
+   * route a single turn to a different model.
+   *
+   * The single invariant this encodes: if the producing model is
+   * thinking-mode, `reasoning_content` MUST be present on the
+   * persisted message — even as an empty string. DeepSeek's validator
+   * 400s the NEXT request if any historical thinking-mode assistant
+   * turn is missing it. We used to gate on `reasoning.length > 0`,
+   * which silently dropped the field whenever the stream emitted zero
+   * reasoning deltas or the API returned `reasoning_content: null` —
+   * both legitimate edge cases the 0.5.15/0.5.18 fixes missed.
+   */
+  assistantMessage(content, toolCalls, producingModel, reasoningContent) {
     const msg = { role: "assistant", content };
     if (toolCalls.length > 0) msg.tool_calls = toolCalls;
-    if (reasoningContent && reasoningContent.length > 0) {
-      msg.reasoning_content = reasoningContent;
+    if (isThinkingModeModel(producingModel)) {
+      msg.reasoning_content = reasoningContent ?? "";
     }
     return msg;
   }
   /**
-   * Build a synthetic assistant message we insert into the log without
-   * a real API round trip (abort notices, future system injections).
-   * Reasoner models reject follow-up requests whose assistant history
-   * is missing `reasoning_content`, so we stamp an empty-string
-   * placeholder on reasoner sessions to satisfy the validator. V3
-   * doesn't care — field stays absent there.
+   * Synthetic assistant message (abort notices, future system injections)
+   * — no real API round trip. Delegates to {@link assistantMessage} with
+   * `this.model` as the stand-in producer, so the same thinking-mode
+   * invariant applies: reasoner sessions get an empty-string
+   * `reasoning_content`; V3 sessions get nothing.
    */
   syntheticAssistantMessage(content) {
-    const msg = { role: "assistant", content };
-    if (isThinkingModeModel(this.model)) {
-      msg.reasoning_content = "";
-    }
-    return msg;
+    return this.assistantMessage(content, [], this.model, "");
   }
 };
 function isThinkingModeModel(model) {
@@ -2753,11 +2827,15 @@ function reasonPrefixFor(reason, iterCap) {
   if (reason === "context-guard") {
     return "[context budget running low \u2014 summarizing before the next call would overflow]";
   }
+  if (reason === "stuck") {
+    return "[stuck on a repeated tool call \u2014 explaining what was tried and what's blocking progress]";
+  }
   return `[tool-call budget (${iterCap}) reached \u2014 forcing summary from what I found]`;
 }
 function errorLabelFor(reason, iterCap) {
   if (reason === "aborted") return "aborted by user";
   if (reason === "context-guard") return "context-guard triggered (prompt > 80% of window)";
+  if (reason === "stuck") return "stuck (repeated tool call suppressed by storm-breaker)";
   return `tool-call budget (${iterCap}) reached`;
 }
 function summarizeBranch(chosen, samples) {
@@ -2897,6 +2975,19 @@ function healLoadedMessages(messages, maxChars) {
   const healedCount = shrunk.healedCount + paired.droppedAssistantCalls + paired.droppedStrayTools;
   return { messages: paired.messages, healedCount, healedFrom: shrunk.healedFrom };
 }
+function stampMissingReasoningForThinkingMode(messages, model) {
+  if (!isThinkingModeModel(model)) {
+    return { messages, stampedCount: 0 };
+  }
+  let stampedCount = 0;
+  const out = messages.map((msg) => {
+    if (msg.role !== "assistant") return msg;
+    if (Object.hasOwn(msg, "reasoning_content")) return msg;
+    stampedCount += 1;
+    return { ...msg, reasoning_content: "" };
+  });
+  return { messages: out, stampedCount };
+}
 function healLoadedMessagesByTokens(messages, maxTokens) {
   const shrunk = shrinkOversizedToolResultsByTokens(messages, maxTokens);
   const paired = fixToolCallPairing(shrunk.messages);
@@ -3212,9 +3303,13 @@ var TUI_FORMATTING_RULES = `Formatting (rendered in a TUI with a real markdown r
 - For flow charts and diagrams: a plain bullet list with \`\u2192\` or \`\u2193\` between steps. Don't try to draw boxes-and-arrows in ASCII; it never survives word-wrap.`;
 var ESCALATION_CONTRACT = `Cost-aware escalation (when you're running on deepseek-v4-flash):
 
-If a task CLEARLY exceeds what flash can do well \u2014 complex cross-file architecture refactors, subtle concurrency / security / correctness invariants you can't resolve with confidence, or a design trade-off you'd be guessing at \u2014 output the exact string \`<<<NEEDS_PRO>>>\` as the FIRST line of your response (nothing before it, not even whitespace on a separate line). This aborts the current call and retries this turn on deepseek-v4-pro, one shot. Do NOT emit any other content in the same response when you request escalation.
+If a task CLEARLY exceeds what flash can do well \u2014 complex cross-file architecture refactors, subtle concurrency / security / correctness invariants you can't resolve with confidence, or a design trade-off you'd be guessing at \u2014 output the marker as the FIRST line of your response (nothing before it, not even whitespace on a separate line). This aborts the current call and retries this turn on deepseek-v4-pro, one shot.
 
-Use this sparingly. Normal tasks \u2014 reading files, small edits, clear bug fixes, straightforward feature additions \u2014 stay on flash. Request escalation ONLY when you would otherwise produce a guess or a visibly-mediocre answer. If in doubt, attempt the task on flash first; the system also escalates automatically if you hit 3+ repair / SEARCH-mismatch errors in a single turn.`;
+Two accepted forms:
+- \`<<<NEEDS_PRO>>>\` \u2014 bare marker, no rationale.
+- \`<<<NEEDS_PRO: <one-sentence reason>>>>\` \u2014 preferred. The reason text appears in the user-visible warning ("\u21E7 flash requested escalation \u2014 <your reason>"), so they understand WHY a more expensive call is happening. Keep it under ~150 chars, no newlines, no nested \`>\` characters. Examples: \`<<<NEEDS_PRO: cross-file refactor across 6 modules with circular imports>>>\` or \`<<<NEEDS_PRO: subtle session-token race; flash would likely miss the locking invariant>>>\`.
+
+Do NOT emit any other content in the same response when you request escalation. Use this sparingly: normal tasks \u2014 reading files, small edits, clear bug fixes, straightforward feature additions \u2014 stay on flash. Request escalation ONLY when you would otherwise produce a guess or a visibly-mediocre answer. If in doubt, attempt the task on flash first; the system also escalates automatically if you hit 3+ repair / SEARCH-mismatch errors in a single turn (the user sees a typed breakdown).`;
 var NEGATIVE_CLAIM_RULE = `Negative claims ("X is missing", "Y isn't implemented", "there's no Z") are the #1 hallucination shape. They feel safe to write because no citation seems possible \u2014 but that's exactly why you must NOT write them on instinct.
 
 If you have a search tool (\`search_content\`, \`grep\`, web search), call it FIRST before asserting absence:
@@ -4439,28 +4534,233 @@ function registerMemoryTools(registry, opts = {}) {
   return registry;
 }
 
-// src/tools/plan.ts
+// src/tools/choice.ts
+var ChoiceRequestedError = class extends Error {
+  question;
+  options;
+  allowCustom;
+  constructor(question, options, allowCustom) {
+    super(
+      "ChoiceRequestedError: choice submitted. STOP calling tools now \u2014 the TUI has shown the options to the user. Wait for their next message; it will either be 'user picked <id>' (carry on with that branch), 'user answered: <text>' (custom free-form reply; read and proceed), or 'user cancelled the choice' (drop the question and ask what they want instead). Don't call any tools in the meantime."
+    );
+    this.name = "ChoiceRequestedError";
+    this.question = question;
+    this.options = options;
+    this.allowCustom = allowCustom;
+  }
+  toToolResult() {
+    return {
+      error: `${this.name}: ${this.message}`,
+      question: this.question,
+      options: this.options,
+      allowCustom: this.allowCustom
+    };
+  }
+};
+function sanitizeOptions(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const e = entry;
+    const id = typeof e.id === "string" ? e.id.trim() : "";
+    const title = typeof e.title === "string" ? e.title.trim() : "";
+    if (!id || !title) continue;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const summary = typeof e.summary === "string" ? e.summary.trim() || void 0 : void 0;
+    const opt = { id, title };
+    if (summary) opt.summary = summary;
+    out.push(opt);
+  }
+  return out;
+}
+function registerChoiceTool(registry, opts = {}) {
+  registry.register({
+    name: "ask_choice",
+    description: "Present 2\u20136 alternatives to the user. The principle: if the user is supposed to pick, the tool picks \u2014 you don't enumerate the choices as prose. Prose menus have no picker in this TUI, so the user gets a wall of text to scroll through and a letter to type, strictly worse than the magenta picker this tool renders. Call it whenever (a) the user has asked for options, (b) you've analyzed multiple approaches and the final call is theirs, or (c) it's a preference fork you can't resolve without them. Skip it when one option is clearly best (just do it, or submit_plan) or a free-form text answer fits (ask in prose). Keep option ids short and stable (A/B/C). Each option: title + optional summary. allowCustom=true when their real answer might not fit. Max 6 options \u2014 narrow first if more. A one-sentence lead-in before the call is fine; don't repeat the options in it.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        question: {
+          type: "string",
+          description: "The question to put in front of the user. One sentence. Don't repeat the options in the question text \u2014 the picker renders them separately."
+        },
+        options: {
+          type: "array",
+          description: "2\u20134 alternatives. Each needs a stable id and a short title; summary is optional.",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string", description: "Short stable id (A, B, C, or option-1)." },
+              title: { type: "string", description: "One-line title shown as the option label." },
+              summary: {
+                type: "string",
+                description: "Optional. A second dimmed line with more detail. Keep under ~80 chars."
+              }
+            },
+            required: ["id", "title"]
+          }
+        },
+        allowCustom: {
+          type: "boolean",
+          description: "If true, the picker shows a 'Let me type my own answer' escape hatch. Default false. Turn on when the user's real answer might not fit any of your pre-defined options."
+        }
+      },
+      required: ["question", "options"]
+    },
+    fn: async (args) => {
+      const question = (args?.question ?? "").trim();
+      if (!question) {
+        throw new Error(
+          "ask_choice: question is required \u2014 write one sentence explaining the decision."
+        );
+      }
+      const options = sanitizeOptions(args?.options);
+      if (options.length < 2) {
+        throw new Error(
+          "ask_choice: need at least 2 well-formed options (each with a non-empty id and title). If you just need a text answer, ask the user in plain assistant text instead."
+        );
+      }
+      if (options.length > 6) {
+        throw new Error(
+          "ask_choice: too many options (max 6). If you really have this many branches, split into two sequential ask_choice calls or narrow down first."
+        );
+      }
+      const allowCustom = args?.allowCustom === true;
+      opts.onChoiceRequested?.(question, options);
+      throw new ChoiceRequestedError(question, options, allowCustom);
+    }
+  });
+  return registry;
+}
+
+// src/tools/plan-errors.ts
 var PlanProposedError = class extends Error {
   plan;
-  constructor(plan) {
+  steps;
+  summary;
+  constructor(plan, steps, summary) {
     super(
       "PlanProposedError: plan submitted. STOP calling tools now \u2014 the TUI has shown the plan to the user. Wait for their next message; it will either approve (you'll then implement the plan), request a refinement (you should explore more and submit an updated plan), or cancel (drop the plan and ask what they want instead). Don't call any tools in the meantime."
     );
     this.name = "PlanProposedError";
     this.plan = plan;
+    this.steps = steps;
+    this.summary = summary;
   }
   /**
    * Structured tool-result shape. Consumed by the TUI to extract the
-   * plan without regex-scraping the error message.
+   * plan without regex-scraping the error message. Optional fields
+   * are omitted from the payload when absent so consumers don't see
+   * `undefined` keys in the JSON.
    */
   toToolResult() {
-    return { error: `${this.name}: ${this.message}`, plan: this.plan };
+    const payload = {
+      error: `${this.name}: ${this.message}`,
+      plan: this.plan
+    };
+    if (this.steps && this.steps.length > 0) payload.steps = this.steps;
+    if (this.summary) payload.summary = this.summary;
+    return payload;
   }
 };
-function registerPlanTool(registry, opts = {}) {
+var PlanCheckpointError = class extends Error {
+  stepId;
+  title;
+  result;
+  notes;
+  constructor(update) {
+    super(
+      "PlanCheckpointError: step complete \u2014 STOP calling tools. The TUI has paused the plan for user review. Wait for the next user message; it will either say continue (proceed to the next step), request a revision (adjust the remaining plan), or stop (summarize and end)."
+    );
+    this.name = "PlanCheckpointError";
+    this.stepId = update.stepId;
+    this.title = update.title;
+    this.result = update.result;
+    this.notes = update.notes;
+  }
+  toToolResult() {
+    const payload = {
+      error: `${this.name}: ${this.message}`,
+      kind: "step_completed",
+      stepId: this.stepId,
+      result: this.result
+    };
+    if (this.title) payload.title = this.title;
+    if (this.notes) payload.notes = this.notes;
+    return payload;
+  }
+};
+var PlanRevisionProposedError = class extends Error {
+  reason;
+  remainingSteps;
+  summary;
+  constructor(reason, remainingSteps, summary) {
+    super(
+      "PlanRevisionProposedError: revision submitted. STOP calling tools now \u2014 the TUI has paused for the user to review your proposed change. Wait for their next message; it will say 'revision accepted' (proceed with the new step list), 'revision rejected' (keep the original plan and continue), or 'revision cancelled' (drop the proposal entirely). Don't call any tools in the meantime."
+    );
+    this.name = "PlanRevisionProposedError";
+    this.reason = reason;
+    this.remainingSteps = remainingSteps;
+    this.summary = summary;
+  }
+  toToolResult() {
+    const payload = {
+      error: `${this.name}: ${this.message}`,
+      reason: this.reason,
+      remainingSteps: this.remainingSteps
+    };
+    if (this.summary) payload.summary = this.summary;
+    return payload;
+  }
+};
+
+// src/tools/plan-core.ts
+var SUBMIT_PLAN_DESCRIPTION = "Submit ONE concrete plan you've already decided on. Use this for tasks that warrant a review gate \u2014 multi-file refactors, architecture changes, anything that would be expensive or confusing to undo. Skip it for small fixes (one-line typo, obvious bug with a clear fix) \u2014 just make the change. The user will either approve (you then implement it), ask for refinement, or cancel. If the user has already enabled /plan mode, writes are blocked at dispatch and you MUST use this. CRITICAL: do NOT use submit_plan to present alternative routes (A/B/C, option 1/2/3) for the user to pick from \u2014 the picker only exposes approve/refine/cancel, so a menu plan strands the user with no way to choose. For branching decisions, call `ask_choice` instead; only call submit_plan once the user has picked a direction and you have a single actionable plan. Write the plan as markdown with a one-line summary, a bulleted list of files to touch and what will change, and any risks or open questions. STRONGLY PREFERRED: pass `steps` \u2014 an array of {id, title, action, risk?} \u2014 so the UI renders a structured step list above the approval picker and tracks per-step progress. Use risk='high' for steps that touch prod data / break public APIs / are hard to undo; 'med' for non-trivial but reversible (multi-file edits, schema tweaks); 'low' for safe local work. After each step, call `mark_step_complete` so the user sees progress ticks.";
+var MARK_STEP_COMPLETE_DESCRIPTION = "Mark one step of the approved plan as done AND pause for the user to review. Call this after finishing each step. The TUI shows a \u2713 progress row and mounts a Continue / Revise / Stop picker \u2014 you MUST stop calling tools after this fires and wait for the next user message. Pass the `stepId` from the plan's steps array, a short `result` (what you did), and optional `notes` for anything surprising (errors, scope changes, follow-ups). This tool doesn't change any files. Don't call it if the plan didn't include structured steps, and don't invent ids that weren't in the original plan.";
+var REVISE_PLAN_DESCRIPTION = "Surgically replace the REMAINING steps of an in-flight plan. Call this when the user has given feedback at a checkpoint that warrants a structured plan change \u2014 skip a step, swap two steps, add a new step, change risk, etc. Pass: `reason` (one sentence why), `remainingSteps` (the new tail of the plan, replacing whatever steps haven't been done yet), and optional `summary` (updated one-line plan summary). Done steps are NEVER touched \u2014 keep them out of `remainingSteps`. The TUI shows a diff (removed in red, kept in gray, added in green) and the user accepts or rejects. Don't call this for trivial mid-step adjustments \u2014 just keep executing. Don't call submit_plan for revisions either \u2014 that resets the whole plan including completed steps. Use submit_plan only when the entire approach has changed; use revise_plan when the tail needs editing.";
+var STEP_ITEM_SCHEMA = {
+  type: "object",
+  properties: {
+    id: { type: "string", description: "Stable id, e.g. step-1." },
+    title: { type: "string", description: "Short imperative title." },
+    action: { type: "string", description: "One-sentence description of the concrete action." },
+    risk: {
+      type: "string",
+      enum: ["low", "med", "high"],
+      description: "Self-assessed risk. 'high' = hard-to-undo / touches prod / breaks API; 'med' = non-trivial but reversible; 'low' = safe local work. The UI shows a colored dot per step so the user knows where to focus review. Omit if you're unsure."
+    }
+  },
+  required: ["id", "title", "action"]
+};
+function sanitizeRisk(raw) {
+  if (raw === "low" || raw === "med" || raw === "high") return raw;
+  return void 0;
+}
+function sanitizeSteps(raw) {
+  if (!Array.isArray(raw)) return void 0;
+  const steps = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const e = entry;
+    const id = typeof e.id === "string" ? e.id.trim() : "";
+    const title = typeof e.title === "string" ? e.title.trim() : "";
+    const action = typeof e.action === "string" ? e.action.trim() : "";
+    if (!id || !title || !action) continue;
+    const step = { id, title, action };
+    const risk = sanitizeRisk(e.risk);
+    if (risk) step.risk = risk;
+    steps.push(step);
+  }
+  return steps.length > 0 ? steps : void 0;
+}
+function registerSubmitPlan(registry, opts) {
   registry.register({
     name: "submit_plan",
-    description: "Submit a concrete plan to the user for review before executing. Use this for tasks that warrant a review gate \u2014 multi-file refactors, architecture changes, anything that would be expensive or confusing to undo. Skip it for small fixes (one-line typo, obvious bug with a clear fix) \u2014 just make the change. The user will either approve (you then implement it), ask for refinement, or cancel. If the user has already enabled /plan mode, writes are blocked at dispatch and you MUST use this. Write the plan as markdown with a one-line summary, a bulleted list of files to touch and what will change, and any risks or open questions.",
+    description: SUBMIT_PLAN_DESCRIPTION,
     readOnly: true,
     parameters: {
       type: "object",
@@ -4468,6 +4768,15 @@ function registerPlanTool(registry, opts = {}) {
         plan: {
           type: "string",
           description: "Markdown-formatted plan. Lead with a one-sentence summary. Then a file-by-file breakdown of what you'll change and why. Flag any risks or open questions at the end so the user can weigh in before you start."
+        },
+        steps: {
+          type: "array",
+          description: "Structured step list (strongly recommended). When provided, the UI renders a compact step list above the approval picker AND tracks per-step progress via `mark_step_complete`. Use stable ids (step-1, step-2, ...). Skip only for tiny one-step plans where the markdown body is enough.",
+          items: STEP_ITEM_SCHEMA
+        },
+        summary: {
+          type: "string",
+          description: "Optional. One-sentence human-friendly title for the plan, ~80 chars max. Surfaces in the PlanConfirm picker header and in /plans listings ('\u25B8 refactor auth into signed tokens \xB7 2/5 done'). Skip for trivial plans where the first line of the markdown body is already short and clear."
         }
       },
       required: ["plan"]
@@ -4477,10 +4786,108 @@ function registerPlanTool(registry, opts = {}) {
       if (!plan) {
         throw new Error("submit_plan: empty plan \u2014 write a markdown plan and try again.");
       }
-      opts.onPlanSubmitted?.(plan);
-      throw new PlanProposedError(plan);
+      const steps = sanitizeSteps(args?.steps);
+      const summary = typeof args?.summary === "string" ? args.summary.trim() || void 0 : void 0;
+      opts.onPlanSubmitted?.(plan, steps);
+      throw new PlanProposedError(plan, steps, summary);
     }
   });
+}
+function registerMarkStepComplete(registry, opts) {
+  registry.register({
+    name: "mark_step_complete",
+    description: MARK_STEP_COMPLETE_DESCRIPTION,
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        stepId: {
+          type: "string",
+          description: "The id of the step being marked complete. Must match one from submit_plan's steps array."
+        },
+        title: {
+          type: "string",
+          description: "Optional. The step's title, echoed back for the UI. If omitted, the UI falls back to the id."
+        },
+        result: {
+          type: "string",
+          description: "One-sentence summary of what was done for this step."
+        },
+        notes: {
+          type: "string",
+          description: "Optional. Anything surprising \u2014 blockers hit, assumptions revised, follow-ups for later steps."
+        }
+      },
+      required: ["stepId", "result"]
+    },
+    fn: async (args) => {
+      const stepId = (args?.stepId ?? "").trim();
+      const result = (args?.result ?? "").trim();
+      if (!stepId) {
+        throw new Error("mark_step_complete: stepId is required.");
+      }
+      if (!result) {
+        throw new Error(
+          "mark_step_complete: result is required \u2014 say in one sentence what you did."
+        );
+      }
+      const title = typeof args?.title === "string" ? args.title.trim() || void 0 : void 0;
+      const notes = typeof args?.notes === "string" ? args.notes.trim() || void 0 : void 0;
+      const update = { kind: "step_completed", stepId, result };
+      if (title) update.title = title;
+      if (notes) update.notes = notes;
+      opts.onStepCompleted?.(update);
+      throw new PlanCheckpointError({ stepId, title, result, notes });
+    }
+  });
+}
+function registerRevisePlan(registry, opts) {
+  registry.register({
+    name: "revise_plan",
+    description: REVISE_PLAN_DESCRIPTION,
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        reason: {
+          type: "string",
+          description: "One sentence explaining why you're revising \u2014 what the user asked for, what changed your assessment."
+        },
+        remainingSteps: {
+          type: "array",
+          description: "The new tail of the plan \u2014 what should run from here on. Each entry: {id, title, action, risk?}. Use stable ids; reuse old ids when a step is just being adjusted, generate new ones for genuinely new steps.",
+          items: STEP_ITEM_SCHEMA
+        },
+        summary: {
+          type: "string",
+          description: "Optional. Updated one-line plan summary if the overall framing has shifted."
+        }
+      },
+      required: ["reason", "remainingSteps"]
+    },
+    fn: async (args) => {
+      const reason = (args?.reason ?? "").trim();
+      if (!reason) {
+        throw new Error(
+          "revise_plan: reason is required \u2014 write one sentence explaining the change."
+        );
+      }
+      const remainingSteps = sanitizeSteps(args?.remainingSteps);
+      if (!remainingSteps || remainingSteps.length === 0) {
+        throw new Error(
+          "revise_plan: remainingSteps must be a non-empty array of well-formed steps. If the user wants to STOP rather than continue, don't revise \u2014 the picker has its own Stop option."
+        );
+      }
+      const summary = typeof args?.summary === "string" ? args.summary.trim() || void 0 : void 0;
+      opts.onPlanRevisionProposed?.(reason, remainingSteps, summary);
+      throw new PlanRevisionProposedError(reason, remainingSteps, summary);
+    }
+  });
+}
+function registerPlanTool(registry, opts = {}) {
+  registerSubmitPlan(registry, opts);
+  registerMarkStepComplete(registry, opts);
+  registerRevisePlan(registry, opts);
   return registry;
 }
 
@@ -4657,8 +5064,8 @@ function registerSubagentTool(parentRegistry, opts) {
         },
         model: {
           type: "string",
-          enum: ["deepseek-v4-flash", "deepseek-v4-pro", "deepseek-chat", "deepseek-reasoner"],
-          description: "Which DeepSeek model the subagent runs on. Default is 'deepseek-v4-pro' \u2014 the strongest model, best for complex subtasks. Override to 'deepseek-v4-flash' (or the legacy 'deepseek-chat' / 'deepseek-reasoner' aliases, which route to flash non-thinking / thinking modes) when the subtask is simple enough that flash's quality suffices \u2014 flash is roughly 12\xD7 cheaper."
+          enum: ["deepseek-v4-flash", "deepseek-v4-pro"],
+          description: "Which DeepSeek model the subagent runs on. Default is 'deepseek-v4-flash' \u2014 cheap and fast, fine for explore/research-style subtasks. Override to 'deepseek-v4-pro' (~12\xD7 more expensive) when the subtask genuinely needs the stronger model: cross-file architecture, subtle bug hunts, anything where flash has empirically underperformed."
         }
       },
       required: ["task"]
@@ -5171,7 +5578,15 @@ async function runCommand(cmd, opts) {
     shell: false,
     // no shell-expansion — see header comment
     windowsHide: true,
-    env: process.env
+    // PYTHONIOENCODING + PYTHONUTF8 force any spawned Python child
+    // (run_command running `python script.py`, etc.) to emit UTF-8
+    // on stdout/stderr. Without this, Chinese-Windows defaults
+    // Python's stdout encoder to GBK and `print("…")` raises
+    // UnicodeEncodeError on emoji / non-GBK chars — the model then
+    // sees a Python traceback instead of the script's real output
+    // and goes around in circles trying to fix the wrong problem.
+    // Harmless on non-Python processes (env vars they don't read).
+    env: { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" }
   };
   const { bin, args, spawnOverrides } = prepareSpawn(argv);
   const effectiveSpawnOpts = { ...spawnOpts, ...spawnOverrides };
@@ -5620,7 +6035,7 @@ function registerWebTools(registry, opts = {}) {
   const maxFetchChars = opts.maxFetchChars ?? DEFAULT_FETCH_MAX_CHARS;
   registry.register({
     name: "web_search",
-    description: "Search the public web. Returns ranked results with title, url, and snippet. Use this when the question needs information more current than your training data, when you're unsure of a factual detail, or when the user asks about a specific webpage/library/release you haven't seen.",
+    description: "Search the public web. Returns ranked results with title, url, and snippet. Call this when the answer's correctness depends on current state \u2014 anything that changes over time (events, prices, releases, status of a thing in the real world). Composing such answers from training memory invents stale numbers; search first, then ground the answer in the results. For evergreen / definitional questions you don't need this.",
     readOnly: true,
     parameters: {
       type: "object",
@@ -6970,6 +7385,21 @@ Skip submit_plan for small, obvious changes: one-line typo, clear bug with a cle
 
 Plan body: one-sentence summary, then a file-by-file breakdown of what you'll change and why, and any risks or open questions. If some decisions are genuinely up to the user (naming, tradeoffs, out-of-scope possibilities), list them in an "Open questions" section \u2014 the user sees the plan in a picker and has a text input to answer your questions before approving. Don't pretend certainty you don't have; flagged questions are how the user tells you what they care about. After calling submit_plan, STOP \u2014 don't call any more tools, wait for the user's verdict.
 
+**Do NOT use submit_plan to present A/B/C route menus.** The approve/refine/cancel picker has no branch selector \u2014 a menu plan strands the user. For branching decisions, use \`ask_choice\` (see below); only call submit_plan once the user has picked a direction and you have ONE actionable plan.
+
+# When to ask the user to pick (ask_choice)
+
+You have an \`ask_choice\` tool. **If the user is supposed to pick between alternatives, the tool picks \u2014 you don't enumerate the choices as prose.** Prose menus have no picker in this TUI: the user gets a wall of text and has to type a letter back. The tool fires an arrow-key picker that's strictly better.
+
+Call it when:
+- The user has asked for options / doesn't want a recommendation / wants to decide.
+- You've analyzed multiple approaches and the final call is theirs.
+- It's a preference fork you can't resolve without them (deployment target, team convention, taste).
+
+Skip it when one option is clearly correct (just do it, or submit_plan) or a free-form text answer fits (ask in prose).
+
+Each option: short stable id (A/B/C), one-line title, optional summary. \`allowCustom: true\` when their real answer might not fit. Max 6. A ~1-sentence lead-in before the call is fine ("I see three directions \u2014 letting you pick"); don't repeat the options in it. After the call, STOP.
+
 # Plan mode (/plan)
 
 The user can ALSO enter "plan mode" via /plan, which is a stronger, explicit constraint:
@@ -7429,6 +7859,7 @@ export {
   AppendOnlyLog,
   CODE_SYSTEM_PROMPT,
   CacheFirstLoop,
+  ChoiceRequestedError,
   DEFAULT_AT_MENTION_MAX_BYTES,
   DEFAULT_MAX_RESULT_CHARS,
   DEFAULT_MAX_RESULT_TOKENS,
@@ -7448,7 +7879,9 @@ export {
   NeedsConfirmationError,
   PROJECT_MEMORY_FILE,
   PROJECT_MEMORY_MAX_CHARS,
+  PlanCheckpointError,
   PlanProposedError,
+  PlanRevisionProposedError,
   SessionStats,
   SseTransport,
   StdioTransport,
@@ -7538,6 +7971,7 @@ export {
   readUsageLog,
   recordFromLoopEvent,
   redactKey,
+  registerChoiceTool,
   registerFilesystemTools,
   registerMemoryTools,
   registerPlanTool,