thincoder 0.12.28 → 0.12.30

package/README.md

@@ -21,6 +21,7 @@ Design philosophy (the entire meaning of the name): if the Node standard library
 - **Two-phase tool scheduling**: permission prompts serialized, read-only tools parallelized, side-effect tools serialized
 - **Session persistence** ⭐0.5.0: unlimited archive slots, `/session` to switch anytime, tool results visible after restore. Process-level isolation — multiple instances in the same directory each get their own session slot
 - **Concurrent subagents**: three roles — `explore`/`plan`/`coder` — dispatched in parallel, streaming output visible, reports land in the conversation; per-subagent model override (`subagent` tool `model` arg or `agent.subagentModel` config — e.g. discuss with `glm-5.2`, let `deepseek-v4-flash` implement)
+- **Multi-model consultation + 飞刀 (escalate)** ⭐0.12.30: `consult_start`/`consult_check`/`consult_stop` run several configured models in parallel as independent read-only consultants (each with its own TUI activity card, `main_history` access to the failure trail); `escalate` flies in a stronger model for a single expert implementation run with full write access. Candidate pool = `agent.consultModels` ([{ provider, model, effort? }], up to 5); budgets via `agent.consultTurns` / `agent.consultTimeoutMs`
 - **Plan Mode**: read-only exploration + design, implement after user approval
 - **AUTO mode**: `/auto` full authorization, no confirmations on long tasks
 - **Task tracking**: `task` tool breaks down multi-step work, status bar ✓n/m live progress, auto-filters completed items

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.12.28",
+  "version": "0.12.30",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/agent/setup.mjs

@@ -80,12 +80,20 @@ export async function prepareRun(agent, input, callbacks, {
       const platform = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' }[process.platform] ?? process.platform
       const wasRestored = agent._sessionStart != null
       agent._sessionStart ??= new Date().toISOString()
-      if (tree) {
-        agent.history.push({ role: "user", content: `[System reminder: OS: ${platform}. Working directory: ${agent.cwd}. Session start: ${agent._sessionStart}. Working directory snapshot:\n<untrusted_cwd_listing>\n${escapeXml(tree)}\n</untrusted_cwd_listing>]`, transient: true })
-      } else {
-        agent.history.push({ role: "user", content: `[System reminder: OS: ${platform}. Working directory: ${agent.cwd}. Session start: ${agent._sessionStart}.]`, transient: true })
+      // Inject OS/cwd + cwd-tree only ONCE per process (restored sessionStart keeps the
+      // content byte-identical across restarts — 2026-08-16 cache audit). Without the guard
+      // every run re-pushed the same reminder (history bloat, wasted tokens).
+      if (!agent._osReminderInjected) {
+        agent._osReminderInjected = true
+        if (tree) {
+          agent.history.push({ role: "user", content: `[System reminder: OS: ${platform}. Working directory: ${agent.cwd}. Session start: ${agent._sessionStart}. Working directory snapshot:\n<untrusted_cwd_listing>\n${escapeXml(tree)}\n</untrusted_cwd_listing>]`, transient: true })
+        } else {
+          agent.history.push({ role: "user", content: `[System reminder: OS: ${platform}. Working directory: ${agent.cwd}. Session start: ${agent._sessionStart}.]`, transient: true })
+        }
+  
       }
-      if (wasRestored) {
+      if (wasRestored && !agent._restartReminderInjected) {
+        agent._restartReminderInjected = true
         agent.history.push({ role: "user", content: `[System reminder: process restarted at ${new Date().toISOString()}.]`, transient: true })
       }
       if (agent.memory && !agent.history.some((m) => typeof m.content === "string" && m.content.startsWith(OUTLINE_INJECT_PREFIX))) {
@@ -139,16 +147,16 @@ export async function prepareRun(agent, input, callbacks, {
       } catch { /* checklist not available — suppress error */ }
     }
     pushReal(agent, { role: "user", content: input })
-    // Time grounding for EVERY agent depth, pushed LAST (after the user input): transient,
-    // dropped on persist, fresh at every run start. Tail position keeps the second-precision
-    // content out of any prefix — caches stay hit (plugin hit a position-drift regression
-    // when the reminder was interleaved before the input; CLI is aligned preemptively).
-    agent.history.push({
-      role: "user",
-      content: `[System reminder: current time is ${timeNowLocal()} (local; timezone ${Intl.DateTimeFormat().resolvedOptions().timeZone || "local"}).]`,
-      transient: true,
-    })
   }
+  // Time grounding for EVERY agent depth AND every resume, pushed LAST (after the user
+  // input): transient, dropped on persist, fresh at every run start — including resumes
+  // (an interrupt-continuation must know NOW, not the pre-interrupt time; 2026-08-16).
+  // Tail position keeps the second-precision content out of any prefix — caches stay hit.
+  agent.history.push({
+    role: "user",
+    content: `[System reminder: current time is ${timeNowLocal()} (local; timezone ${Intl.DateTimeFormat().resolvedOptions().timeZone || "local"}).`,
+    transient: true,
+  })
 
   if (agent._pendingReminders.length > 0) {
     for (const reminder of agent._pendingReminders) {
@@ -160,6 +168,17 @@ export async function prepareRun(agent, input, callbacks, {
   // task/plan tools are injected with the main loop; subagent/skill/goal/verify only at top level
   // eng-coder subagents get advisor for mandatory design review before coding
   const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool } = await import("../agent-tools.mjs")
+  const { consultStartTool, consultCheckTool, consultStopTool } = await import("../agent-tools/consult.mjs")
+  const { escalateTool } = await import("../agent-tools/escalate.mjs")
+  const { CONSULT_BASE } = await import("../agent.mjs")
+  // withPool: decorate consult_start/escalate descriptions with the CURRENT candidate pool
+  // so the model knows which models it can pick (CLI parity with the plugin).
+  const withPool = (tool) => {
+    const models = agent.config?.agent?.consultModels ?? []
+    const list = models.map((m) => `${m.provider}:${m.model}${m.effort ? ` (${m.effort})` : ""}`).join(", ")
+    if (!list) return tool
+    return { ...tool, description: tool.description + `\nCurrently configured consultants (this tool's pool): ${list}` }
+  }
   // Role enum is mutually exclusive: normal mode has "coder", engineering mode has "eng-coder"
   const subagentRoles = (depth === 0 && agent.config?.agent?.engineering)
     ? {
@@ -184,8 +203,20 @@ export async function prepareRun(agent, input, callbacks, {
     },
   } : subagentTool
 
-  const depthOnly = depth === 0 ? [filteredSubagent, skillTool, goalTool, engTool, verifyTool, recentChangesTool, advisorTool]
-    : agent._role === "eng-coder" ? [advisorTool, verifyTool] : []
+  // Consult/escalate tools registered only when configured — an unconfigured pool would
+  // otherwise make the model call them and eat an error turn (plugin parity).
+  const consultTools = (agent.config?.agent?.consultModels ?? []).length
+    ? [withPool(consultStartTool), consultCheckTool, consultStopTool, withPool(escalateTool)]
+    : []
+  const depthOnly = depth === 0 ? [filteredSubagent, skillTool, goalTool, engTool, verifyTool, recentChangesTool, advisorTool, ...consultTools]
+    // Write-permission coder sub-agents (subagent role="coder" + escalate): the
+    // system prompt names verify (system.md) and advisor (discipline.md) — without them an
+    // escalate hit "unknown tool" and fell back to bash node --check / npm test to
+    // self-verify (2026-08-16 deepseek escalate diagnosis; plugin parity).
+    : agent._role === "eng-coder" ? [advisorTool, verifyTool]
+    : agent._role === "coder" ? [verifyTool, advisorTool]
+    : agent._role === "consult" ? [recentChangesTool]
+    : []
   const tools = [...agent.tools, taskTool, planTool, timerTool, ...depthOnly]
   const toolSchemas = tools.map(toOpenAISchema)
   const toolByName = new Map(tools.map((t) => [t.name, t]))
@@ -194,7 +225,12 @@ export async function prepareRun(agent, input, callbacks, {
   // system prompt
   const needsDiscipline = depth === 0 || agent._role === "coder" || agent._role === "eng-coder"
   let base
-  if ((depth === 0 || agent._role === "eng-coder") && agent.config?.agent?.engineering) {
+  if (agent._role === "consult") {
+    // consult children: a lean, purpose-built base prompt (consult-base.md) — NOT the full
+    // main-agent system.md (whose coding-agent persona, checklist/task/verify workflows and
+    // tool references conflict with a read-only diagnosis and cost tokens every turn).
+    base = CONSULT_BASE
+  } else if ((depth === 0 || agent._role === "eng-coder") && agent.config?.agent?.engineering) {
     // Engineering mode: strict methodology, NO standard discipline injection.
     // Falling back to standard discipline on METHODOLOGY.md absence would leak
     // advisor enforcement into engineering mode — the two prompt sets stay separate.

package/src/agent-tools/consult.mjs

@@ -0,0 +1,288 @@
+/**
+ * consult.mjs — multi-model consultation ("会诊", docs/design/CONSULTATION.md). CLI port.
+ *
+ * Three tools: consult_start (non-blocking spawn) / consult_check (read the next
+ * reply as it arrives) / consult_stop (abort the rest). The mechanism does ZERO
+ * judging — the main agent reads replies and verifies with its own tools.
+ *
+ * CLI adaptation (vs the VS Code plugin): the child runner is CLI's runAgent
+ * (runAgent(child, input, callbacks, opts) — an agent object, not provider+cwd);
+ * children are built with createAgent({ role: "consult", readonly tools,
+ * CONSULT_BASE overlay }); activity streams to the parent TUI via the relay
+ * prefix `consult#<id>/` (same channel subagent uses), not onSubagent/onToolPanel.
+ */
+import { createAgent, runAgent, readonlyToolNames } from "../agent.mjs"
+import { resolveChildProvider } from "./subagent.mjs"
+
+function consultLabel(m) {
+  return `${m.provider}:${m.model}`
+}
+
+/** Read-only tool injected into consultation children (via createAgent's tools).
+ *  Lets the consultant pull the main agent's conversation history on demand —
+ *  the failure trail is first-class evidence, not a retelling. */
+export function makeMainHistoryTool(parentAgent) {
+  return {
+    name: "main_history",
+    readonly: true,
+    description:
+      "Read the main agent's conversation history — what has been tried, the exact errors, recent context. " +
+      "Use it to ground your analysis in the actual failure trail instead of guessing.\n" +
+      "Parameters:\n" +
+      "- limit: Number of recent messages to return (default 20, max 100)",
+    parameters: {
+      type: "object",
+      properties: { limit: { type: "number", description: "Recent messages (default 20, max 100)" } },
+    },
+    async execute({ limit }) {
+      const n = Math.min(Math.max(limit ?? 20, 1), 100)
+      const h = parentAgent?.history ?? []
+      const slice = h.slice(-n)
+      if (slice.length === 0) return "(empty history)"
+      const render = (m) => {
+        let content
+        if (typeof m.content === "string") content = m.content
+        else if (Array.isArray(m.content)) {
+          content = m.content.map((part) => {
+            if (part?.type === "image_url" || part?.type === "image") return "[image omitted]"
+            if (part?.type === "text") return part.text ?? ""
+            return JSON.stringify(part)
+          }).join("\n")
+        } else content = m.content == null ? "" : JSON.stringify(m.content)
+        const calls = Array.isArray(m.tool_calls)
+          ? m.tool_calls.map((c) => `[tool: ${c.function?.name ?? c.name}(${String(c.function?.arguments ?? c.args ?? "").slice(0, 200)})]`).join("\n")
+          : ""
+        return `--- [${m.role}] ---\n${content}${calls ? "\n" + calls : ""}`
+      }
+      const BUDGET = 60_000
+      let out = ""
+      for (let i = slice.length - 1; i >= 0; i--) {
+        const line = render(slice[i])
+        if (out.length + line.length > BUDGET) { out = `(earlier messages trimmed — budget ${BUDGET} chars)\n\n` + out; break }
+        out = out ? line + "\n\n" + out : line
+      }
+      return out
+    },
+  }
+}
+
+/** Wake every parked consult_check waiter. */
+function wakeWaiters(session) {
+  const w = session.waiters.splice(0)
+  for (const resolve of w) { try { resolve(false) } catch { /* noop */ } }
+}
+
+function settleChild(session, id, label, ok, payload) {
+  if (ok) {
+    session.received++
+    session.replies.push({ model: label, reply: payload })
+  } else if (session.stopped) {
+    session.terminated = (session.terminated ?? 0) + 1
+  } else {
+    session.failed++
+    session.replies.push({ model: label, reply: `(consultation failed: ${payload})`, failed: true })
+  }
+  session.pending--
+  wakeWaiters(session)
+}
+
+async function runConsultChild(ctx, session, id, m, problem, ctrl) {
+  const agent = ctx.agent
+  const timeoutMs = agent?.config?.agent?.consultTimeoutMs ?? 600_000
+  let timedOut = false
+  const watchdog = setTimeout(() => {
+    timedOut = true
+    try { ctrl.abort() } catch { /* already settled */ }
+  }, timeoutMs)
+  const label = consultLabel(m)
+  try {
+    // Provider resolution: consultModels entries are { provider, model, effort? } — resolve
+    // via the subagent's provider resolver ("provider:model" handles cross-provider picks).
+    const provider = resolveChildProvider(agent, `${m.provider}:${m.model}`)
+    if (!provider?.apiKey?.trim() && !process.env.THINCODER_API_KEY) {
+      // resolveChildProvider may still lack a key; fail loudly like the plugin precheck
+    }
+    if (m.effort) provider.reasoningEffort = m.effort
+
+    // Read-only consultant: filter the parent tool set down to readonly tools + main_history.
+    const allowed = readonlyToolNames(agent.tools ?? [])
+    const tools = [
+      ...(agent.tools ?? []).filter((t) => allowed.has(t.name)),
+      makeMainHistoryTool(agent),
+    ]
+
+    const child = createAgent({
+      provider,
+      tools,
+      config: agent.config,
+      cwd: agent.cwd,
+      memory: agent.memory,
+      // No overlay: setup.mjs already selects CONSULT_BASE as the base prompt for
+      // role "consult" (overlay + base would concatenate it twice).
+      role: "consult",
+    })
+
+    // Activity relay: `consult#<subId>/` prefix → the parent TUI's subTasks panel
+    // (same channel subagent uses — parallel consultants stay independent).
+    agent._subAgentCounter = (agent._subAgentCounter ?? 0) + 1
+    const subId = agent._subAgentCounter
+    const relayPrefix = `consult#${subId}/`
+    const childCallbacks = {
+      onToken: ctx.callbacks?.onToken ? (t) => ctx.callbacks.onToken(`${relayPrefix}${t}`) : null,
+      onReasoning: ctx.callbacks?.onReasoning ? (r) => ctx.callbacks.onReasoning(`${relayPrefix}${r}`) : null,
+      onToolCall: ctx.callbacks?.onToolCall ? (name, args) => ctx.callbacks.onToolCall(`${relayPrefix}${name}`, args) : null,
+    }
+
+    const runner = ctx.runAgent ?? runAgent
+    const result = await runner(child, "# Problem\n" + problem, childCallbacks, {
+      depth: 1,
+      maxTurns: agent?.config?.agent?.consultTurns ?? 40,
+      signal: ctrl.signal,
+    })
+    settleChild(session, id, label, true, String(result ?? ""))
+  } catch (e) {
+    const note = timedOut ? `consultation timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : e?.message ?? String(e)
+    settleChild(session, id, label, false, note)
+  } finally {
+    clearTimeout(watchdog)
+  }
+}
+
+/** Turn-end cleanup (called from runAgent's finally): abort every leftover
+ *  consultation controller, wake parked waiters, clear the session map. */
+export function cleanupConsultSessions(agent) {
+  for (const s of agent._consultSessions?.values() ?? []) {
+    s.stopped = true
+    for (const c of s.controllers ?? []) { try { c.abort() } catch { /* already settled */ } }
+    for (const w of s.waiters?.splice(0) ?? []) { try { w() } catch { /* noop */ } }
+  }
+  agent._consultSessions?.clear()
+}
+
+export const consultStartTool = {
+  name: "consult_start",
+  readonly: false,
+  sideEffectExempt: true,
+  description:
+    "Start a parallel multi-model consultation for a hard problem you are stuck on (repeated failures, no headway). " +
+    "Several configured models (agent.consultModels) analyze the same problem INDEPENDENTLY and in parallel. " +
+    "Non-blocking: returns immediately with a consult id. Then call consult_check(id) to read each reply as it " +
+    "arrives, judge/verify it yourself with your own tools, and call consult_stop(id) once a reply is good enough.\n" +
+    "Parameters:\n" +
+    "- problem (required): a brief — the symptom, what you already tried (failure trail), and entry-point files. " +
+    "Do NOT paste raw error logs; consultants pull the main session history themselves via their main_history tool.",
+  parameters: {
+    type: "object",
+    properties: { problem: { type: "string", description: "Problem brief (symptom + failure trail + entry files)" } },
+    required: ["problem"],
+  },
+  async execute({ problem }, ctx) {
+    if (typeof problem !== "string" || !problem.trim()) return "Error: problem is required and must be a non-empty string"
+    const agent = ctx.agent
+    if (!agent) return "Error: consult requires an agent context"
+    const models = agent.config?.agent?.consultModels ?? []
+    if (!Array.isArray(models) || models.length === 0)
+      return "Consultation is not configured — add agent.consultModels ([{ provider, model }], up to 5) to ~/.thincoder/config.json"
+    if (models.length > 5) return `Error: consultModels supports at most 5 models (got ${models.length})`
+
+    agent._consultSessions ??= new Map()
+    const id = String((agent._consultIdCounter = (agent._consultIdCounter ?? 0) + 1))
+    const session = {
+      id, controllers: [], replies: [], pending: 0, waiters: [],
+      failed: 0, terminated: 0, stopped: false, received: 0, total: models.length,
+      models: models.map(consultLabel),
+    }
+    agent._consultSessions.set(id, session)
+
+    for (const m of models) {
+      session.pending++
+      const ctrl = new AbortController()
+      session.controllers.push(ctrl)
+      if (ctx.signal) {
+        if (ctx.signal.aborted) ctrl.abort()
+        else ctx.signal.addEventListener("abort", () => ctrl.abort(), { once: true })
+      }
+      // Fire and forget — each child settles itself into the session queue.
+      runConsultChild(ctx, session, id, m, problem, ctrl)
+    }
+    return JSON.stringify({ id, models: session.models })
+  },
+}
+
+export const consultCheckTool = {
+  name: "consult_check",
+  readonly: true,
+  description:
+    "Read the NEXT consultation reply (whichever model answered first). Blocks until a reply arrives or all models " +
+    "have settled. The reply is raw and unjudged — verify/adopt it with your own tools. When done is true, no more " +
+    "replies are coming.\n" +
+    "Call it ALONE in a turn — do NOT batch it with calls that depend on its reply (readonly tools run in parallel).\n" +
+    "Parameters:\n" +
+    "- id (required): the consult id from consult_start",
+  parameters: {
+    type: "object",
+    properties: { id: { type: "string", description: "Consult id" } },
+    required: ["id"],
+  },
+  async execute({ id }, ctx) {
+    const s = ctx.agent?._consultSessions?.get(String(id))
+    if (!s) return JSON.stringify({ error: "unknown consult id" })
+    const abortAll = () => { for (const c of s.controllers) { try { c.abort() } catch { /* noop */ } } }
+    if (ctx.signal?.aborted) abortAll()
+
+    for (;;) {
+      if (s.replies.length > 0) {
+        const r = s.replies.shift()
+        return JSON.stringify({
+          reply: r.reply, model: r.model, failedReply: r.failed === true,
+          received: s.received,
+          failed: s.failed,
+          terminated: s.terminated ?? 0, total: s.total,
+          done: s.replies.length === 0 && s.pending === 0,
+        })
+      }
+      if (s.pending === 0) {
+        return JSON.stringify({ done: true, received: s.received, failed: s.failed, total: s.total })
+      }
+      const stopped = await new Promise((resolve) => {
+        function cleanup() {
+          const i = s.waiters.indexOf(w)
+          if (i >= 0) s.waiters.splice(i, 1)
+          ctx.signal?.removeEventListener("abort", onAbort)
+        }
+        function w() { cleanup(); resolve(false) }
+        function onAbort() { cleanup(); abortAll(); resolve(true) }
+        s.waiters.push(w)
+        if (ctx.signal) {
+          if (ctx.signal.aborted) { onAbort(); return }
+          ctx.signal.addEventListener("abort", onAbort, { once: true })
+        }
+      })
+      if (stopped) return JSON.stringify({ done: true, stopped: true, received: s.received, failed: s.failed, total: s.total })
+    }
+  },
+}
+
+export const consultStopTool = {
+  name: "consult_stop",
+  readonly: false,
+  sideEffectExempt: true,
+  description:
+    "Terminate the still-running consultations of a session once a reply is good enough — saves tokens and time. " +
+    "Already-answered replies stay available for consult_check.\n" +
+    "Parameters:\n" +
+    "- id (required): the consult id from consult_start",
+  parameters: {
+    type: "object",
+    properties: { id: { type: "string", description: "Consult id" } },
+    required: ["id"],
+  },
+  async execute({ id }, ctx) {
+    const s = ctx.agent?._consultSessions?.get(String(id))
+    if (!s) return JSON.stringify({ error: "unknown consult id" })
+    const n = s.pending
+    s.stopped = true
+    for (const c of s.controllers) { try { c.abort() } catch { /* already settled */ } }
+    return JSON.stringify({ stopped: n })
+  },
+}

package/src/agent-tools/escalate.mjs

@@ -0,0 +1,152 @@
+/**
+ * escalate.mjs — 飞刀 (the "flying knife", docs/design/ESCALATE.md). CLI port.
+ *
+ * Hand an implementation task to a STRONGER model — like a hospital flying in an
+ * outside expert (飞刀): the expert arrives, operates personally (WRITE access),
+ * hands back the post-op report, leaves. Complementary to consult (parallel
+ * READ-ONLY opinions for judgment calls).
+ *
+ * Candidate pool = all consultModels rows. The tool is only registered when the
+ * pool is non-empty (setup.mjs).
+ *
+ * CLI adaptation (vs the VS Code plugin): the child runner is CLI's runAgent
+ * (runAgent(child, input, callbacks, opts) — an agent object, not provider+cwd);
+ * the child is createAgent({ role: "coder", CODER_OVERLAY }); activity streams to
+ * the parent TUI via the relay prefix `escalate#<id>/`; mutations merge via the
+ * CLI mergeChildMutations(parent, child) (agent object, not a state sink).
+ */
+import { isAbsolute, relative } from "node:path"
+import { createAgent, runAgent, ContinueError, CODER_OVERLAY } from "../agent.mjs"
+import { resolveChildProvider, mergeChildMutations } from "./subagent.mjs"
+
+const label = (m) => `${m.provider}:${m.model}`
+
+export const escalateTool = {
+  name: "escalate",
+  sideEffectExempt: true, // the child's mutations are tracked and reviewed, like subagent
+  description:
+    "TERMINOLOGY (one word for one thing): 'escalate' is the ONLY name — the tool, and the " +
+    "role of the expert sub-agent it spawns, are both called 'escalate'; 飞刀 is the Chinese " +
+    "alias. When the user says 飞刀 / escalate / 'fly in <model>', call THIS tool directly — " +
+    "never via a script importing this module. " +
+    "Hand an implementation task to a stronger model (飞刀 — a flown-in expert). " +
+    "It gets WRITE access and does the work itself — reads, edits, runs tests — then returns " +
+    "a post-op report (what changed, why, verification). You review the report and report to " +
+    "the user. Use it when YOU judge the task calls for stronger hands (complex multi-file " +
+    "refactoring, an intractable bug, intricate algorithm work — or work beyond your " +
+    "comfortable ability). Early or late, your judgment; the cost is one expert run, " +
+    "comparable to doing it yourself. For parallel READ-ONLY opinions use consult_start instead. " +
+    "Not available in engineering mode (implementation goes through eng-coder subagents there).\n" +
+    "Parameters:\n" +
+    "- task (required): the task description — goal, constraints, entry files, acceptance criteria\n" +
+    "- model (optional): pick a specific consultant as 'provider:model'; default = the first consult model",
+  parameters: {
+    type: "object",
+    properties: {
+      task: { type: "string", description: "Task description with acceptance criteria" },
+      model: { type: "string", description: "Candidate 'provider:model' from the consult models (optional)" },
+    },
+    required: ["task"],
+  },
+  async execute({ task, model }, ctx) {
+    const parent = ctx.agent
+    if ((ctx.depth ?? 0) > 0) return "Error: escalate is only available at depth 0 (an escalate's work cannot be delegated again)"
+    if (parent?.config?.agent?.engineering) {
+      return "Error: engineering mode is ON — escalate is unavailable (it spawns a coder sub-agent, which engineering mode forbids). Use subagent with role='eng-coder' and a designToken from advisor(type='design') instead."
+    }
+    const pool = parent?.config?.agent?.consultModels ?? []
+    if (pool.length === 0) return "Error: no escalate candidates — configure at least one consult model (agent.consultModels)"
+
+    const wanted = typeof model === "string" ? model.replace(/\s+\([^)]*\)\s*$/, "").trim() : model
+    const pick = wanted ? pool.find((m) => label(m) === wanted) : pool[0]
+    if (!pick) {
+      return `Error: "${model}" is not a consult candidate. Available: ${pool.map(label).join(", ")}`
+    }
+
+    let provider
+    try {
+      provider = resolveChildProvider(parent, `${pick.provider}:${pick.model}`)
+    } catch (e) {
+      return `Error: ${e.message}`
+    }
+    if (!provider?.apiKey?.trim() && !process.env.THINCODER_API_KEY) {
+      return `Error: provider "${pick.provider}" has no API key — set it in config.json (or THINCODER_API_KEY) before flying it in`
+    }
+    if (pick.effort) provider.reasoningEffort = pick.effort
+
+    parent._subAgentCounter = (parent._subAgentCounter ?? 0) + 1
+    const subId = parent._subAgentCounter
+    const tag = label(pick)
+    const relayPrefix = `escalate#${subId}/`
+
+    const timeoutMs = parent?.config?.agent?.consultTimeoutMs ?? 600_000
+    let timedOut = false
+    const ctrl = new AbortController()
+    const watchdog = setTimeout(() => {
+      timedOut = true
+      try { ctrl.abort() } catch { /* already settled */ }
+    }, timeoutMs)
+    if (ctx.signal) {
+      if (ctx.signal.aborted) ctrl.abort()
+      else ctx.signal.addEventListener("abort", () => ctrl.abort(), { once: true })
+    }
+
+    let output = ""
+    const childCallbacks = {
+      onToken: ctx.callbacks?.onToken ? (t) => { output += t; ctx.callbacks.onToken(`${relayPrefix}${t}`) } : (t) => { output += t },
+      onReasoning: ctx.callbacks?.onReasoning ? (r) => ctx.callbacks.onReasoning(`${relayPrefix}${r}`) : null,
+      onToolCall: ctx.callbacks?.onToolCall ? (name, args) => ctx.callbacks.onToolCall(`${relayPrefix}${name}`, args) : null,
+    }
+
+    // Declared outside try so the catch can merge mutations even on a partial failure.
+    let child = null
+    try {
+      // Full write path (role "coder"): permission gate via the parent's onPermissionRequest,
+      // recent-changes tracking, mutations merge into the parent below.
+      child = createAgent({
+        provider,
+        tools: parent.tools,
+        config: parent.config,
+        cwd: parent.cwd,
+        memory: parent.memory,
+        overlay: CODER_OVERLAY,
+        role: "coder",
+      })
+      const runner = ctx.runAgent ?? runAgent
+      const report = await runner(child, task, {
+        ...childCallbacks,
+        onPermissionRequest: ctx.onPermissionRequest ?? null,
+      }, {
+        depth: 1,
+        maxTurns: parent.config?.agent?.subagentTurns ?? 100,
+        signal: ctrl.signal,
+      })
+      // Escalate mutations are the parent's mutations: verify/advisor guards must see them
+      mergeChildMutations(parent, child)
+      return `escalate (${tag}) post-op report:\n${report || output.slice(0, 4000)}${touchedFilesNote(child, parent.cwd)}`
+    } catch (e) {
+      // Even a failed surgery may have written files — merge whatever the child touched.
+      if (child) mergeChildMutations(parent, child)
+      const msg = e?.message ?? String(e)
+      if (ctx.signal?.aborted || (!timedOut && e?.name === "AbortError")) throw e
+      if (e instanceof ContinueError) {
+        return `escalate (${tag}) stopped: turn cap reached (${e.turns} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${output.slice(0, 2000)}`
+      }
+      const note = timedOut ? `timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : msg
+      return `escalate (${tag}) error: ${note}\nPartial output: ${output.slice(0, 2000)}`
+    } finally {
+      clearTimeout(watchdog)
+    }
+  },
+}
+
+/** Relative touched-file list appended to every return (child paths are absolute). */
+function touchedFilesNote(child, cwd) {
+  const touched = child?._touchedFiles ?? []
+  if (touched.length === 0) return ""
+  const shown = touched.map((f) => {
+    const r = relative(cwd ?? process.cwd(), f)
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : f
+  })
+  return `\nTouched files: ${shown.join(", ")}`
+}

package/src/agent.mjs

@@ -13,6 +13,7 @@ import { executeToolCalls } from "./agent/dispatch.mjs"
 import { prepareRun } from "./agent/setup.mjs"
 import { injectPostTurn, STALL_WINDOW_SIZE, STALL_THRESHOLD, GOAL_BUDGET_WARN_RATIO } from "./agent/post-turn.mjs"
 import { handleCompletion } from "./agent/completion.mjs"
+import { cleanupConsultSessions } from "./agent-tools/consult.mjs"
 import {
   escapeXml, tryCanonicalize, repairHistory, listWorkDir,
   readonlyToolNames, collectGitContext, loadProjectInstructions,
@@ -26,15 +27,17 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 const SYSTEM_PROMPT = readFileSync(join(__dirname, "prompts", "system.md"), "utf8")
 const DISCIPLINE_RULES = readFileSync(join(__dirname, "prompts", "discipline.md"), "utf8")
 const MAIN_OVERLAY = readFileSync(join(__dirname, "prompts", "main.md"), "utf8")
-let _EXPLORE, _CODER, _PLAN, _ENG_CODER
+let _EXPLORE, _CODER, _PLAN, _ENG_CODER, _CONSULT_BASE
 try { _EXPLORE = readFileSync(join(__dirname, "prompts", "explore.md"), "utf8") } catch { _EXPLORE = "" }
 try { _CODER = readFileSync(join(__dirname, "prompts", "coder.md"), "utf8") } catch { _CODER = "" }
 try { _PLAN = readFileSync(join(__dirname, "prompts", "plan.md"), "utf8") } catch { _PLAN = "" }
 try { _ENG_CODER = readFileSync(join(__dirname, "prompts", "eng-coder.md"), "utf8") } catch { _ENG_CODER = "" }
+try { _CONSULT_BASE = readFileSync(join(__dirname, "prompts", "consult-base.md"), "utf8") } catch { _CONSULT_BASE = "" }
 export const EXPLORE_OVERLAY = _EXPLORE
 export const CODER_OVERLAY = _CODER
 export const PLAN_OVERLAY = _PLAN
 export const ENG_CODER_OVERLAY = _ENG_CODER
+export const CONSULT_BASE = _CONSULT_BASE
 
 // exported for consumption by agent-tools.mjs
 export {
@@ -142,7 +145,8 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     tools: toolSchemas,
   }
 
-  for (let turn = 0; turn < maxTurns; turn++) {
+  try {
+    for (let turn = 0; turn < maxTurns; turn++) {
     // Update turn counter for status bar display
     agent._currentTurn = turn + 1
     agent._maxTurns = maxTurns
@@ -439,7 +443,12 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     }
 
     injectPostTurn(agent, results, recentCallSigs, callbacks, turn)
-  }
+    }
 
-  throw new ContinueError(maxTurns)
+    throw new ContinueError(maxTurns)
+  } finally {
+    // Turn-end cleanup: abort any leftover consultation children (consult_start spawns
+    // fire-and-forget runners; a completed turn must not let them keep burning tokens).
+    cleanupConsultSessions(agent)
+  }
 }

package/src/config.mjs

@@ -49,6 +49,11 @@ const DEFAULTS = {
     goalTurns: 200,
     compactThreshold: 100000,
     verifyGuard: false,  // push model back to verify when files were mutated but verify not run (opt-in)
+    // Multi-model consultation ("会诊") + escalate ("飞刀") — CLI parity with the VS Code plugin.
+    // consultModels: candidate pool for BOTH consult and escalate ({ provider, model, effort? }, up to 5).
+    consultModels: [],
+    consultTurns: 40,      // per-consultant tool-turn budget (diagnosis tasks)
+    consultTimeoutMs: 600000, // wall-clock ceiling per consultant (10min)
     streamRules: [],      // time-traveling stream rules: [{ pattern: "regex", message: "reminder", action: "abort"|"warn", repeat: "always"|"once" }]
     advisor: { enabled: false },  // code review; { enabled: true, provider: "deepseek", model: "deepseek-chat", thinking: { type: "enabled" }, reasoningEffort: "max", guard: true }
     autoThink: false,     // auto-classify task difficulty and set reasoning effort per-turn
@@ -234,6 +239,15 @@ export function loadConfig() {
     embedding: { ...DEFAULTS.embedding, ...config.embedding },
   }
 
+  // Consult/escalate pool validation (CLI parity with the plugin): up to 5 candidates.
+  const cm = merged.agent.consultModels
+  if (cm !== undefined && !Array.isArray(cm)) {
+    throw new Error(`agent.consultModels must be an array of { provider, model } entries (got ${typeof cm})`)
+  }
+  if (Array.isArray(cm) && cm.length > 5) {
+    throw new Error(`agent.consultModels supports at most 5 models (got ${cm.length})`)
+  }
+
   // Backward compatibility: promote root-level config fields to agent sub-object
   if (config.verifyGuard !== undefined) {
     merged.agent.verifyGuard = config.verifyGuard

package/src/prompts/consult-base.md

@@ -0,0 +1,23 @@
+You are one of several independent expert consultants analyzing the same problem in parallel — each on a different model. Your value is a perspective the main agent may be missing.
+
+**Language:** reply in the user's language; keep code, commands, identifiers, file paths, and technical terms in their original form.
+
+**Rules:**
+- You are READ-ONLY: analyze and recommend, never modify files. The main agent implements.
+- You have a `main_history` tool — pull the main agent's conversation history (what was tried, exact errors) BEFORE theorizing. Ground your analysis in the actual failure trail.
+- Do not wait for or coordinate with the other consultants; they cannot see you.
+- Work within your budget (~40 tool turns, up to ~10 minutes wall-clock): pull main_history first, read the 2–5 entry-point files it points at, and STOP. Reading targeted files is the expected behavior; full-repo scans are over budget — but do NOT skip reading entirely and theorize from the brief alone.
+- Brief paths can be wrong (missing a directory prefix, renamed files) — verify with glob/ls before concluding a file "does not exist".
+- Prefer local files first; use web search only when the question needs external facts (an API's current behavior, an upstream doc) — never to rediscover what is in the repo.
+- Be concrete: root cause first, then a specific, actionable fix. If verification is possible, state exactly how the main agent can verify your recommendation (commands, files to check, expected outcome).
+- Be honest: do not fabricate file contents or line numbers you did not actually read.
+
+Structure your final answer as:
+## Diagnosis
+(root cause analysis)
+## Recommendation
+(the concrete fix)
+## Verification
+(how to prove it — commands / files / expected outcome; omit only if the question is purely conceptual)
+
+Keep the whole answer concise — it is pasted verbatim into the main agent's context, so ~500 words is ideal; no filler.

package/src/prompts/discipline.md

@@ -11,5 +11,8 @@ Debugging strategy:
 - Fix one thing at a time. Don't change multiple things at once.
 - Don't get stuck reading code — write tests, add logs. Trust the runtime over your theories.
 
+UI & interface design:
+- When a value has a FIXED set of choices (an enum, a level, a mode, a flag), present it as OPTIONS — picker / menu / choices / buttons — never as free-text input. Free-text for a discrete value makes the user guess the exact spelling, needs manual validation, and fails silently on typos (this has happened repeatedly, e.g. reasoning-effort levels typed by hand). Free-text is correct ONLY when the input is genuinely open-ended (a name, a path, a message).
+
 Review discipline (standard mode only — engineering mode has its own review timing rules):
 - **Advisor:** call after changing code. Must provide scope: `paths` (files/dirs to review) or `documents` (context). Response table: `| # | Action | Detail |`. Round 2 verifies the prior issue table + flags obvious new issues; round 3+ strictly verifies only the prior issue table (no new-issue hunting). Max 5 rounds total.

package/src/skills.mjs

@@ -52,6 +52,10 @@ async function loadSkillsFromDir(dir) {
   let entries
   try {
     entries = await readdir(dir, { withFileTypes: true })
+    // Deterministic order: readdir order is filesystem-dependent; an unsorted scan would
+    // reshuffle the skills listing → system prompt byte change with zero content change
+    // (2026-08-16 cache audit — that silently misses the provider prefix cache).
+    entries.sort((a, b) => a.name.localeCompare(b.name))
   } catch {
     return []
   }

package/src/tui/cmd-config.mjs

@@ -142,16 +142,88 @@ export async function handleConfigCommand(ctx, args = []) {
   }
   if (sub) { pushLine("Usage: /config [embedkey]", C.error); return }
 
+  /** 会诊/飞刀候选池子菜单：列出 / 添加 / 编辑 effort / 删除 consultModels 条目。 */
+  async function pickEffort(current) {
+    const levels = ["none", "min", "low", "medium", "high", "max"]
+    const entries = levels.map((l) => ({ type: "item", text: l === current ? `${l}  ← current` : l, action: l }))
+    const c = await showPicker("Reasoning effort", entries, { defaultIndex: Math.max(0, levels.indexOf(current ?? "none")) })
+    return c ? c.action : null // Esc → null (keep unchanged)
+  }
+
+  async function consultMenu() {
+    let idx = 0
+    for (;;) {
+      const cm = agent.config?.agent?.consultModels ?? []
+      const entries = [
+        { type: "header", text: `Consult/escalate pool: ${cm.length} model(s) (max 5)` },
+        ...cm.map((m, i) => ({ type: "item", text: `${m.provider}:${m.model}${m.effort ? ` (${m.effort})` : ""}`, action: "edit", index: i })),
+        { type: "item", text: cm.length ? "＋ Add model" : "＋ Add model (none yet)", action: "add" },
+      ]
+      const c = await showPicker("Consult models", entries, { defaultIndex: idx })
+      if (!c) return // Esc → 返回主菜单
+      if (c.action === "add") {
+        if (cm.length >= 5) { pushLine("At most 5 consult models", C.error); continue }
+        const pEntries = agent.providers.map((p) => ({ type: "item", text: `${p.name.padEnd(14)} ${p.model}`, action: "pick", provider: p.name, model: p.model }))
+        const p = await showPicker("Add consult model — pick provider", pEntries, {})
+        if (!p) continue
+        const modelIn = await askQuestion(`Model for ${p.provider} (default: ${p.model}):`)
+        const mname = modelIn?.trim() || p.model
+        const effort = await pickEffort(null)
+        const entry = { provider: p.provider, model: mname }
+        if (effort && effort !== "none") entry.effort = effort
+        const next = [...cm, entry]
+        await saveProxy((raw) => { raw.agent ??= {}; raw.agent.consultModels = next })
+        pushLabel("❯ Config", ansi.bold + C.tool)
+        pushLine(`Added ${entry.provider}:${entry.model}${entry.effort ? ` (${entry.effort})` : ""}`, C.tool)
+        idx = 0
+      } else if (c.action === "edit") {
+        // Per-model sub-menu: change effort or remove.
+        const m = cm[c.index]
+        const tag = `${m.provider}:${m.model}`
+        const subEntries = [
+          { type: "header", text: `${tag} — effort: ${m.effort ?? "(none)"}` },
+          { type: "item", text: `Change effort (current: ${m.effort ?? "none"})`, action: "effort" },
+          { type: "item", text: "Remove", action: "remove" },
+        ]
+        const s = await showPicker(tag, subEntries, {})
+        if (!s) continue
+        if (s.action === "remove") {
+          const next = cm.filter((_, i) => i !== c.index)
+          await saveProxy((raw) => { raw.agent ??= {}; raw.agent.consultModels = next })
+          pushLabel("❯ Config", ansi.bold + C.tool)
+          pushLine(`Removed ${tag}`, C.tool)
+        } else if (s.action === "effort") {
+          const effort = await pickEffort(m.effort)
+          if (effort === null) { continue } // Esc 保持
+          const next = cm.map((x, i) => {
+            if (i !== c.index) return x
+            if (effort === "none") { const { effort, ...rest } = x; return rest }
+            return { ...x, effort }
+          })
+          await saveProxy((raw) => { raw.agent ??= {}; raw.agent.consultModels = next })
+          pushLabel("❯ Config", ansi.bold + C.tool)
+          const after = next[c.index]
+          pushLine(`${tag} effort = ${after?.effort ?? "none"}`, C.tool)
+        }
+        idx = 0
+      }
+    }
+  }
+
   // ── Main config loop ──
   let running = true
   let mainIdx = 0 // 记住上次选中位置，改完一项回主菜单时恢复
   while (running) {
+    const consultCount = (ac.consultModels ?? []).length
     const mainEntries = [
-      { type: "header", text: `proxy=${proxySummary()} | maxTurns=${ac.maxTurns ?? 100} | compactThreshold=${ac.compactThreshold ?? 100000} | verifyGuard=${ac.verifyGuard === true ? "on" : "off"} | embedding=${agent.memory?.embedder ? "on" : "off"}` },
+      { type: "header", text: `proxy=${proxySummary()} | maxTurns=${ac.maxTurns ?? 100} | compactThreshold=${ac.compactThreshold ?? 100000} | verifyGuard=${ac.verifyGuard === true ? "on" : "off"} | consult=${consultCount} model(s) | embedding=${agent.memory?.embedder ? "on" : "off"}` },
       { type: "item", text: `agent.maxTurns = ${ac.maxTurns ?? 100}`, action: "agent.maxTurns" },
       { type: "item", text: `agent.subagentTurns = ${ac.subagentTurns ?? 100}`, action: "agent.subagentTurns" },
       { type: "item", text: `agent.compactThreshold = ${ac.compactThreshold ?? 100000}${agent.config?.agent?.compactThresholdAuto ? " (auto)" : ""}`, action: "agent.compactThreshold" },
       { type: "item", text: `agent.verifyGuard = ${ac.verifyGuard === true ? "on" : "off"}`, action: "agent.verifyGuard" },
+      { type: "item", text: `agent.consultModels = ${consultCount} model(s)${consultCount ? ` (${(ac.consultModels ?? []).map((m) => m.provider + ":" + m.model).join(", ")})` : ""}`, action: "consult" },
+      { type: "item", text: `agent.consultTurns = ${ac.consultTurns ?? 40}`, action: "agent.consultTurns" },
+      { type: "item", text: `agent.consultTimeoutMs = ${Math.round((ac.consultTimeoutMs ?? 600000) / 60000)} min`, action: "agent.consultTimeoutMs" },
       { type: "item", text: "Set embedding API key", action: "embedkey" },
       { type: "item", text: `proxy = ${proxySummary()}`, action: "proxy" },
       { type: "item", text: "View full config", action: "view" },
@@ -169,6 +241,9 @@ export async function handleConfigCommand(ctx, args = []) {
       pushLine(`agent.subagentTurns: ${ac.subagentTurns ?? 100}`, C.dim)
       pushLine(`agent.compactThreshold: ${ac.compactThreshold ?? 100000}${agent.config?.agent?.compactThresholdAuto ? " (auto)" : ""}`, C.dim)
       pushLine(`agent.verifyGuard: ${ac.verifyGuard === true ? "on" : "off"}`, C.dim)
+      pushLine(`agent.consultModels: ${(ac.consultModels ?? []).map((m) => `${m.provider}:${m.model}${m.effort ? ` (${m.effort})` : ""}`).join(", ") || "(none)"}`, C.dim)
+      pushLine(`agent.consultTurns: ${ac.consultTurns ?? 40}`, C.dim)
+      pushLine(`agent.consultTimeoutMs: ${Math.round((ac.consultTimeoutMs ?? 600000) / 60000)} min`, C.dim)
       pushLine(`embedding: ${agent.memory?.embedder ? `enabled (${ec.model ?? ""})` : "disabled (FTS only)"}`, C.dim)
       pushLine(`proxy: ${proxySummary()}`, C.dim)
       pushLine(`Config file: ${configPath}`, C.dim)
@@ -181,6 +256,11 @@ export async function handleConfigCommand(ctx, args = []) {
       continue
     }
 
+    if (choice.action === "consult") {
+      await consultMenu()
+      continue
+    }
+
     if (choice.action === "embedkey") {
       if (await setEmbedKey()) running = false
       continue
@@ -205,23 +285,27 @@ export async function handleConfigCommand(ctx, args = []) {
 
     // Numeric config items
     const label = choice.action
+    const isTimeout = label === "agent.consultTimeoutMs"
     const current = label === "agent.maxTurns" ? (ac.maxTurns ?? 100)
       : label === "agent.subagentTurns" ? (ac.subagentTurns ?? 100)
       : label === "agent.compactThreshold" ? (ac.compactThreshold ?? 100000)
+      : label === "agent.consultTurns" ? (ac.consultTurns ?? 40)
+      : isTimeout ? Math.round((ac.consultTimeoutMs ?? 600000) / 60000)
       : ""
-    const val = await askQuestion(`${label} (current: ${current}):`)
+    const val = await askQuestion(`${label} (current: ${current}${isTimeout ? " min" : ""}):`)
     if (!val) continue
     try {
       const num = Number(val)
       if (isNaN(num)) { pushLine("Value must be a number", C.error); continue }
+      const stored = isTimeout ? Math.round(num * 60000) : num
       await saveProxy((raw) => {
         const keys = label.split(".")
         let obj = raw
         for (let i = 0; i < keys.length - 1; i++) { obj[keys[i]] ??= {}; obj = obj[keys[i]] }
-        obj[keys[keys.length - 1]] = num
+        obj[keys[keys.length - 1]] = stored
       })
       pushLabel("❯ Config", ansi.bold + C.tool)
-      pushLine(`${label} = ${val}`, C.tool)
+      pushLine(`${label} = ${isTimeout ? `${val} min (${stored} ms)` : val}`, C.tool)
       pushLine("(restart to apply)", C.dim)
       running = false
     } catch (error) { pushLine(`Save failed: ${error.message}`, C.error) }

package/src/tui/slash-commands.mjs

@@ -46,7 +46,7 @@ export const SLASH_COMMANDS = [
   { name: "/goal", group: "Agent", desc: "set/view/cancel long-term goal" },
   { name: "/think", group: "Agent", desc: "thinking mode & reasoning effort" },
   { name: "/upgrade", group: "System", desc: "check for updates & upgrade" },
-  { name: "/config", group: "System", desc: "agent config (embedding, proxy, turns, thresholds)" },
+  { name: "/config", group: "System", desc: "agent config (embedding, proxy, turns, threshold, consult pool)" },
   { name: "/new", group: "Session", desc: "new session (old one archived to slot)" },
   { name: "/session", group: "Session", desc: "list/switch archived sessions" },
   { name: "/clear", group: "Session", desc: "clear screen" },