thincoder 0.12.58 → 0.12.59

package/src/agent-tools/consult.mjs

@@ -13,6 +13,7 @@
  */
 import { createAgent, runAgent, readonlyToolNames } from "../agent.mjs"
 import { resolveChildProvider } from "./subagent.mjs"
+import { logEvent, errText } from "../log.mjs"
 import { makeRelay, wrapChildCallbacks, runWithContinue, ensureChildApiKey, clampEffort } from "../agent/spawn-child.mjs"
 
 // Named consult defaults (consult P2, 2026-08-30).
@@ -27,7 +28,7 @@ function consultLabel(m) {
 /** Narrow the configured consultModels pool to a requested subset.
  *  Each selector is "provider:model", a bare provider name, or a bare model name
  *  (case-insensitive). A trailing " (effort)" suffix is tolerated (round2 复核
- *  对齐 escalate.mjs：withPool 列表会带 " (high)" 后缀，模型照抄应可匹配).
+ *  对齐 escalate 动作（subagent action:"escalate"）：withPool 列表会带 " (high)" 后缀，模型照抄应可匹配).
  *  Returns { models, error } — error set when a selector matches
  *  nothing (surface the typo rather than silently dropping it). Absent/empty selectors
  *  → the full pool. */
@@ -145,6 +146,21 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
   }
   let watchdog = armWatchdog()
   const label = consultLabel(m)
+  // LOGGING（LOGGING.md）：child:*（consult）——logSettle 在函数作用域声明（外层 catch
+  // 覆盖 spawn 前失败路径）；spawn 事件在 relay 建立后发射（logArmed 翻转——provider/
+  // 创建失败 = 从未启动，不落子事件、错误仅经 settleChild 进会话）。
+  let childLogId = null
+  let logT0 = 0
+  let logArmed = false
+  let logDone = false
+  const logSettle = (kind, payload) => {
+    if (!logArmed || logDone || !childLogId) return
+    logDone = true
+    const ms = Date.now() - logT0
+    const base = { role: "consult", id: childLogId, ms }
+    if (kind === "ok" || kind === "partial") logEvent("child:done", { ...base, kind })
+    else logEvent("child:error", { ...base, err: errText(payload, 200) })
+  }
   try {
     // Provider resolution: consultModels entries are { provider, model, effort? } — resolve
     // via the subagent's provider resolver ("provider:model" handles cross-provider picks).
@@ -156,9 +172,10 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     }
     // Clamp the pool's effort to the model's reasoningEffortEnum — an out-of-enum
     // value makes provider/core throw on EVERY chat call (candidate dies on takeoff).
-    // Symmetric with escalate.mjs; 2026-08-16 a real consult died on qwen3.8-max
-    // effort "high" (enum is xhigh/medium/low). Out-of-enum: DROP the effort entirely
-    // (the provider preset default may ALSO be out-of-enum for this override model).
+    // Symmetric with the escalate action (subagent action:"escalate"); 2026-08-16
+    // a real consult died on qwen3.8-max effort "high" (enum is xhigh/medium/low).
+    // Out-of-enum: DROP the effort entirely (the provider preset default may ALSO be
+    // out-of-enum for this override model).
     clampEffort(provider, m.model, m.effort)
 
     // Read-only consultant: filter the parent tool set down to readonly tools + main_history.
@@ -183,6 +200,12 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     // prefix (same channel subagent uses — parallel consultants stay independent) +
     // onToolOutput passthrough so the consultant's tool output lands in its TUI block.
     const relayPrefix = makeRelay(agent, "consult", ctx.callbacks?.onToken, provider.model ?? "")
+    // LOGGING：arm（spawn 事件——relay 建立后；子内事件归属 _logId）
+    childLogId = relayPrefix.slice(0, -1)
+    child._logId = childLogId
+    logT0 = Date.now()
+    logArmed = true
+    logEvent("child:spawn", { role: "consult", id: childLogId, kind: "consult" })
     const childCallbacks = wrapChildCallbacks(relayPrefix, ctx.callbacks ?? {})
     let declined = false // review #1: guard against double-settle when onDeclined fired
 
@@ -216,6 +239,7 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
           onDeclined: (e) => {
             declined = true
             settleChild(session, id, label, false, `turn cap reached (${e.turn} turns) — stopped, diagnosis may be partial`)
+            logSettle("partial", null)
             return undefined
           },
         },
@@ -224,18 +248,23 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
       // settling again here would push a phantom empty success reply and decrement
       // `pending` twice (negative pending → consult_check's two exits both
       // unreachable → permanent block until user abort).
-      if (!declined) settleChild(session, id, label, true, String(result ?? ""))
+      if (!declined) {
+        settleChild(session, id, label, true, String(result ?? ""))
+        logSettle("ok", null)
+      }
     } catch (e) {
       // Runner errors (incl. the watchdog's abort) settle as a failed reply — the
       // continue/declined paths are already handled inside runWithContinue.
       const note = timedOut ? `consultation timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : e?.message ?? String(e)
       settleChild(session, id, label, false, note)
+      logSettle("error", note)
     }
   } catch (e) {
     // Errors BEFORE the runner (provider resolution, createAgent) or a throwing
     // continue-prompt settle as failed replies — the runner's own errors are already
     // handled inside the loop above.
     settleChild(session, id, label, false, e?.message ?? String(e))
+    logSettle("error", e?.message ?? String(e))
   } finally {
     clearTimeout(watchdog)
   }
@@ -326,6 +355,7 @@ export const consultCheckTool = {
     "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" +
     "Replies arrive in arrival order: call it repeatedly (n = 1, 2, 3, …) until done is true.\n" +
+    "Returns JSON: {reply, model, failedReply, received, failed, terminated, total, done} for a reply — or {done: true, received, failed, total} when none are left.\n" +
     "Parameters:\n" +
     "- id (required): the consult id from consult_start\n" +
     "- n (required): the 1-based read number for this consult — pass 1 on the first check, 2 on the next, and so on. It exists so consecutive checks are distinct tool calls (loop detectors) and the transcript reads as a sequence.",
@@ -382,7 +412,8 @@ export const consultStopTool = {
   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" +
+    "Already-answered replies stay available for consult_check. " +
+    "Returns JSON {stopped: <n>, abandoned: <pending count>} — or {error: \"unknown consult id\"}.\n" +
     "Parameters:\n" +
     "- id (required): the consult id from consult_start\n" +
     "- n (required): incrementing call number for this consult (next value after the last consult_check/consult_stop) — keeps repeated calls distinct.",

package/src/agent-tools/eng.mjs

@@ -8,7 +8,8 @@ import { ENG_ON_REMINDER, ENG_OFF_REMINDER } from "../agent.mjs"
 export const engTool = {
   name: "eng",
   description:
-    "Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents.",
+    "Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents. " +
+    "Returns the mode state — 'Engineering mode activated/exited' (an already-active state is acknowledged).",
   parameters: {
     type: "object",
     properties: {

package/src/agent-tools/goal.mjs

@@ -11,7 +11,8 @@ export const goalTool = {
     "action='set': create or replace the goal — must have a verifiable completion criterion (a machine-checkable proof, not vague effort). " +
     "action='complete': mark achieved — only after the criterion's check has actually passed. " +
     "action='blocked': report an impasse (requires 'reason') — only after 3 genuine attempts. " +
-    "action='cancel': abandon the goal.",
+    "action='cancel': abandon the goal. " +
+    "Returns a status line — the goal set/updated/completed/blocked/cancelled confirmation, or Error: ... with the reason.",
   parameters: {
     type: "object",
     properties: {
@@ -76,6 +77,15 @@ Has this goal been achieved? Answer ONLY "YES" or "NO" followed by a one-sentenc
             }],
             tools: [],
             signal: AbortSignal.timeout(10_000),
+            // §18.6 D-TR4/D-TR6（2026-09-04 fix round1）：goal 独立评审调用经 chat()
+            // 唯一采集点——补轨迹元数据 + traces 开关透传（agent.config.traces.enabled
+            // ——关=不落盘必须全覆盖——与 agent.mjs/context.mjs 同模式）
+            logCtx: {
+              stage: "goal", kind: "goal",
+              role: agent._role ?? null, depth: ctx.depth,
+              session: agent._sessionStart ?? null, cwd: agent.cwd,
+              traces: agent.config?.traces?.enabled !== false,
+            },
           })
           const verdict = (judgeRes.content ?? "").trim()
           if (verdict.toUpperCase().startsWith("NO")) {

package/src/agent-tools/read-history.mjs

@@ -0,0 +1,160 @@
+/**
+ * agent-tools/read-history.mjs — read_history tool (SESSION.md §9).
+ *
+ * Query THIS session's message history — the full human-readable record
+ * (agent._fullHistory — NEVER compacted, audit-complete). Use to recall what
+ * was said or done earlier: design decisions, tool-call timing, past rulings.
+ *
+ * Filters AND together: role / keyword (message text) / tool (tool messages by
+ * name + assistant messages that declared the call) / since-until (epoch ms
+ * window, inclusive-inclusive, matches ONLY messages that carry ts) /
+ * limit (default 50, clamped to 200) / direction (oldest/newest — which end of
+ * the matched set the limit window is taken from).
+ *
+ * Returns a JSON array in chronological order. Every message without ts comes
+ * back as ts:null and can never match a time window (legacy sessions). Content
+ * is truncated to ~500 chars with an explicit marker — full text lives in the
+ * session file. assistant tool_calls are summarized to a name list (arguments
+ * never expanded).
+ *
+ * readonly: true — planMode pass / no permission ask. Registered depth-0 only:
+ * subagents get their own throwaway history, so querying "the session" from a
+ * child would be semantically confusing (SESSION.md §9.5 refinement 1).
+ * Mirrored 1:1 in thincoder-vscode/src/agent-tools/read-history.mjs.
+ */
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 200
+const CONTENT_CAP = 500
+const VALID_ROLES = new Set(["user", "assistant", "tool"])
+
+/** Message text for keyword matching + output: strings pass through; multimodal content arrays → text parts joined (never crashes, empty parts skipped, images ignored). */
+function messageText(m) {
+  if (typeof m?.content === "string") return m.content
+  if (Array.isArray(m?.content)) {
+    return m.content
+      .map((p) => (p && typeof p === "object" && p.type === "text" ? p.text ?? "" : ""))
+      .filter((t) => t.length > 0)
+      .join(" ")
+  }
+  return ""
+}
+
+/** Truncate long content (~500 chars) with an explicit marker. The cut never splits a UTF-16
+ *  surrogate pair (emoji etc.) — a lone high surrogate in tool output would be an eyesore at
+ *  minimum; the send layer sanitizes it anyway, but clean output costs nothing (setup.mjs
+ *  safeSliceUTF16 same rule). */
+function truncateContent(text) {
+  const t = String(text ?? "")
+  if (t.length <= CONTENT_CAP) return t
+  let end = CONTENT_CAP
+  if (t.charCodeAt(end - 1) >= 0xd800 && t.charCodeAt(end - 1) <= 0xdbff) end-- // high surrogate at the cut → step back
+  return t.slice(0, end) + `\n… (truncated: ${t.length - end} chars — full text is in the session file)`
+}
+
+/** Tool name across both stored shapes ({function:{name}} and flat {name}). */
+function toolCallName(tc) {
+  return tc?.function?.name ?? tc?.name ?? ""
+}
+
+/** Parse a ts window boundary (epoch ms number; numeric strings tolerated). Returns the number or an error string. */
+function parseTs(value, label) {
+  if (value === undefined || value === null) return null
+  const n = typeof value === "number" ? value : Number(value)
+  if (!Number.isFinite(n)) return `Error: invalid ${label} "${value}" — must be epoch milliseconds (number)`
+  return n
+}
+
+/** Map one matched message to its JSON entry shape. */
+function toEntry(m) {
+  const entry = {
+    ts: typeof m.ts === "number" ? m.ts : null,
+    role: m.role ?? null,
+  }
+  if (m.name !== undefined) entry.name = m.name
+  if (m.tool_call_id !== undefined) entry.tool_call_id = m.tool_call_id
+  entry.content = truncateContent(messageText(m))
+  if (Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
+    entry.tool_calls = m.tool_calls.map(toolCallName).filter(Boolean)
+  }
+  return entry
+}
+
+export const readHistoryTool = {
+  name: "read_history",
+  description:
+    "Query THIS session's message history (the full record — never compacted, audit-complete). " +
+    "Use when you need to recall what was said or done earlier: design decisions, tool-call timing, past rulings. " +
+    "Filters combine with AND: role / keyword (case-insensitive substring of message text) / " +
+    "tool (tool result messages by name AND the assistant messages that declared the call — pair with tool_call_id / ts for timing) / " +
+    "since-until (epoch ms time window; only messages with ts can match) / limit (default 50, clamped to 200) / direction (which end of the matches to take). " +
+    "Returns a JSON array in chronological order: [{ts, role, name?, tool_call_id?, content (≈500 chars, truncated marker), tool_calls (names only)}]. " +
+    "Messages without ts return ts:null. Content is truncated — the full text is in the session file. " +
+    "For file-level changes this run (not messages), use recent_changes.",
+  parameters: {
+    type: "object",
+    properties: {
+      role: { type: "string", enum: ["user", "assistant", "tool"], description: "Only messages with this role." },
+      keyword: { type: "string", description: "Case-insensitive substring of the message text (multimodal messages match on their text parts)." },
+      tool: { type: "string", description: "Only messages for this tool: role=tool messages with name=tool, plus assistant messages that declared a call to it." },
+      since: { type: "integer", description: "Earliest ts to match, epoch ms, INCLUSIVE. Messages without ts never match a time window." },
+      until: { type: "integer", description: "Latest ts to match, epoch ms, INCLUSIVE. since > until yields an empty result." },
+      limit: { type: "integer", description: "Maximum messages to return (default 50; larger values are clamped to 200)." },
+      direction: { type: "string", enum: ["oldest", "newest"], description: "Take the limit window from the oldest or newest end of the matched set (default newest)." },
+    },
+  },
+  readonly: true,
+  execute(args, ctx) {
+    const a = args ?? {}
+    const role = a.role
+    if (role !== undefined && (typeof role !== "string" || !VALID_ROLES.has(role))) {
+      return `Error: invalid role "${role}" — valid roles: user, assistant, tool`
+    }
+    const direction = a.direction ?? "newest"
+    if (direction !== "oldest" && direction !== "newest") {
+      return `Error: invalid direction "${direction}" — valid values: oldest, newest`
+    }
+    const since = parseTs(a.since, "since")
+    if (typeof since === "string") return since
+    const until = parseTs(a.until, "until")
+    if (typeof until === "string") return until
+    let limit = DEFAULT_LIMIT
+    if (a.limit !== undefined) {
+      limit = Math.floor(Number(a.limit))
+      if (!Number.isFinite(limit)) return `Error: invalid limit "${a.limit}" — must be a number`
+      limit = Math.min(Math.max(1, limit), MAX_LIMIT)
+    }
+    const keyword = typeof a.keyword === "string" && a.keyword.length > 0 ? a.keyword : null
+    // Case-insensitive substring WITHOUT copying the full message text: the human line is
+    // never compacted — single tool results can be hundreds of KB to MBs. Lowercase the
+    // needle once and run a regex-i test over the haystack (escaping regex metachars so the
+    // keyword stays a literal substring).
+    const kwRe = keyword ? new RegExp(keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i") : null
+    const tool = typeof a.tool === "string" && a.tool.length > 0 ? a.tool : null
+
+    const history = Array.isArray(ctx.agent?._fullHistory) ? ctx.agent._fullHistory : []
+    const matched = history.filter((m) => {
+      if (!m || typeof m !== "object") return false
+      if (role !== undefined && m.role !== role) return false
+      if (kwRe) {
+        const text = messageText(m)
+        if (!kwRe.test(text)) return false
+      }
+      if (tool) {
+        const byName = m.role === "tool" && m.name === tool
+        const byDeclaration = m.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.some((tc) => toolCallName(tc) === tool)
+        if (!byName && !byDeclaration) return false
+      }
+      const ts = m.ts
+      if (since !== null || until !== null) {
+        if (typeof ts !== "number") return false // no ts → no time-window match
+        if (since !== null && ts < since) return false
+        if (until !== null && ts > until) return false
+      }
+      return true
+    })
+    // Direction picks the END of the matched set; output stays chronological either way.
+    const windowed = direction === "oldest" ? matched.slice(0, limit) : matched.slice(-limit)
+    return JSON.stringify(windowed.map(toEntry))
+  },
+}

package/src/agent-tools/settings.mjs

@@ -0,0 +1,162 @@
+/**
+ * settings tool — agent-side configuration adjustment (SETTINGS-TOOL.md, 2026-09-05).
+ * 用户裁定：全量 config.json 任意键（点分路径）+ 单工具多动作 list/get/set + 双端同批。
+ * 语义：set = 写盘（config.json——磁盘真相最小化：只写被设的键——默认值不固化）+
+ * 热应用（ctx.agent.config 内存对象立即更新——回合边界键下回合生效）。
+ * 护栏：敏感键（路径段含 apiKey/key/token/secret/password）回显/错误文本永不出现明文
+ * （••••（masked）——防密钥泄漏进会话历史/trace）；已知键类型校验（类型表自动派生自
+ * config.mjs DEFAULTS——不手写防漂移）；set 侧效走审批门（dispatch 动作级分类）。
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { DEFAULTS, configPath } from "../config.mjs"
+
+/** 敏感键段判定（完整点分路径的段级匹配——apiKey/api_key/api-key/token/secret/password 形态） */
+const SENSITIVE_SEGMENT = /(^|[._-])(api[_-]?key|key|token|secret|password)($|[._-])/i
+const MASKED = "••••（masked）"
+
+function isSensitiveKey(path) {
+  return SENSITIVE_SEGMENT.test(path)
+}
+
+/**
+ * 类型表：递归遍历 DEFAULTS——叶子（非对象/数组值）记 `路径 → typeof 默认值`。
+ * 数组（providersList 等）不递归（下标元素无类型约束——全量域）；对象节递归到叶子。
+ */
+function buildTypeMap(obj, prefix = "", out = {}) {
+  for (const [k, v] of Object.entries(obj)) {
+    const p = prefix ? `${prefix}.${k}` : k
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) buildTypeMap(v, p, out)
+    else out[p] = Array.isArray(v) ? "array" : typeof v
+  }
+  return out
+}
+const TYPE_MAP = buildTypeMap(DEFAULTS)
+
+/** 点分路径解析（含数组数字段）——逐段下钻；返回 { ok, value } 或缺失段信息 */
+function resolvePath(obj, path) {
+  const segs = String(path).split(".")
+  let cur = obj
+  for (let i = 0; i < segs.length; i++) {
+    if (cur === null || typeof cur !== "object" || !(segs[i] in cur)) {
+      return { ok: false, reached: segs.slice(0, i).join("."), missing: segs[i], depth: i }
+    }
+    cur = cur[segs[i]]
+  }
+  return { ok: true, value: cur }
+}
+
+/** 点分路径写入（自动建中间对象——cmd-config 数值项同款）；返回旧值 */
+function setKeyPath(obj, path, value) {
+  const segs = String(path).split(".")
+  let cur = obj
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (cur[segs[i]] === null || typeof cur[segs[i]] !== "object") cur[segs[i]] = {}
+    cur = cur[segs[i]]
+  }
+  const last = segs[segs.length - 1]
+  const old = cur[last]
+  cur[last] = value
+  return old
+}
+
+/** 递归展平 config 对象（数组下标段形态）→ 排序的 { path, value } 列表 */
+function flatten(obj, prefix = "", out = []) {
+  for (const [k, v] of Object.entries(obj)) {
+    const p = prefix ? `${prefix}.${k}` : k
+    if (v !== null && typeof v === "object") flatten(v, p, out)
+    else out.push({ path: p, value: v })
+  }
+  return out.sort((a, b) => (a.path < b.path ? -1 : 1))
+}
+
+/** 行格式化：`key = value (type)`——敏感键值遮罩 */
+function formatLine({ path, value }) {
+  const shown = isSensitiveKey(path) ? MASKED : value
+  return `${path} = ${shown} (${Array.isArray(value) ? "array" : typeof value})`
+}
+
+function parseValue(raw) {
+  const s = String(raw)
+  try {
+    const v = JSON.parse(s)
+    // JSON 顶层标量都接受；解析失败（裸字符串）→ 字符串字面
+    if (typeof v === "number" || typeof v === "boolean" || v === null || Array.isArray(v) || typeof v === "object") return v
+    return s // "abc"（带引号传的字符串）——JSON.parse 成功但返回字符串——保持解析结果
+  } catch {
+    return s // 裸 abc → 字符串字面
+  }
+}
+
+export function settingsTool(opts = {}) {
+  const cfgPath = opts.configPath ?? configPath // 测试注入 tmp 文件；默认全局 configPath
+
+  async function readDisk() {
+    let text
+    try { text = readFileSync(cfgPath, "utf8") } catch { return {} } // 不存在 → 空对象（写盘最小化——默认不固化）
+    try { return JSON.parse(text) } catch { throw new Error(`settings: config file not parseable — refusing to overwrite: ${cfgPath}`) }
+  }
+  async function writeDisk(disk) {
+    mkdirSync(join(cfgPath, ".."), { recursive: true })
+    writeFileSync(cfgPath, JSON.stringify(disk, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
+  }
+
+  return {
+    name: "settings",
+    description:
+      "Adjust ThinCoder runtime configuration — persisted to config.json AND hot-applied to the live agent config.\n" +
+      "Actions: list (all keys + values, flattened) | get <key> | set <key> <value> — dot paths into config.json (agent.maxTurns, traces.enabled, providers.0.model, any nesting).\n" +
+      "set persists to disk (only the set key is written — defaults are never baked in) and takes effect in the running session immediately (turn-boundary keys apply next turn); the value survives restarts.\n" +
+      "Known keys are type-checked against the built-in defaults (agent.maxTurns must be a number, traces.enabled a boolean); unknown keys under a known section are stored as given. Values parse as JSON first (true/false/numbers/objects/arrays), else stay strings.\n" +
+      "SENSITIVE keys (path segment contains apiKey/key/token/secret/password) are NEVER echoed in plaintext — list/get/set replies show ••••（masked）; setting a sensitive key is allowed and stored, but never echoed back.\n" +
+      "list/get are read-only (planMode ok, no approval); set is a side effect (approval gate). The /config TUI command is the human equivalent.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["list", "get", "set"], description: "list — full key/value inventory; get <key> — one value; set <key> <value> — persist + hot-apply" },
+        key: { type: "string", description: "Dot path into config.json, e.g. agent.maxTurns / traces.enabled / providers.0.model" },
+        value: { type: "string", description: "New value for set — parsed as JSON first (true/5/{...}/[...]), otherwise kept as string" },
+      },
+      required: ["action"],
+    },
+    readonly: false, // set 是侧效——dispatch 动作级分类放行 list/get
+    async execute(args, ctx) {
+      const action = args?.action
+      if (!["list", "get", "set"].includes(action)) throw new Error(`settings: action must be one of list/get/set — got ${JSON.stringify(action)}`)
+      const config = ctx?.agent?.config ?? null
+      if (!config) throw new Error("settings: no live agent config (ctx.agent.config missing)")
+      if (action === "list") {
+        const rows = flatten(config)
+        if (rows.length === 0) return "（空配置——无已设置键）"
+        return rows.map(formatLine).join("\n")
+      }
+      if (action === "get") {
+        if (!args.key) throw new Error("settings get: key is required (dot path, e.g. agent.maxTurns)")
+        const r = resolvePath(config, args.key)
+        if (!r.ok) {
+          const hint = r.depth === 0 ? "（config 顶层无此键——顶层可用键见 settings list）" : `（父键 ${r.reached || "顶层"} 存在——无 ${r.missing} 子键）`
+          throw new Error(`settings get: no such key "${args.key}" ${hint}`)
+        }
+        return formatLine({ path: args.key, value: r.value })
+      }
+      // set
+      if (!args.key || args.value === undefined) throw new Error("settings set: key and value are required")
+      const value = parseValue(args.value)
+      // 已知键类型校验（类型表派生自 DEFAULTS——未知键 JSON 原样）
+      const want = TYPE_MAP[String(args.key)]
+      if (want && want !== "array") {
+        const got = value === null ? "null" : typeof value
+        if (got !== want && !(value === null && want === "object")) {
+          throw new Error(`settings set: "${args.key}" expects ${want} — got ${got} (${JSON.stringify(args.value)})`)
+        }
+      }
+      // 写盘（磁盘真相最小化：只改被设键——默认不固化）+ 热应用（内存对象）
+      const disk = await readDisk()
+      setKeyPath(disk, args.key, value)
+      await writeDisk(disk)
+      setKeyPath(config, args.key, value)
+      const shown = isSensitiveKey(String(args.key)) ? MASKED : value
+      return `settings set: ${args.key} = ${shown} (${Array.isArray(value) ? "array" : typeof value})${isSensitiveKey(String(args.key)) ? " — stored（值不回显）" : " — persisted + hot-applied（运行中已生效）"}`
+    },
+  }
+}

package/src/agent-tools/skill.mjs

@@ -9,7 +9,8 @@ import { escapeXml } from "../agent.mjs"
 export const skillTool = {
   name: "skill",
   description:
-    "Load a project skill from .thincoder/skills/. Skills contain reusable instructions, workflows, or reference material. Use this when the user references a skill by name, or when a task matches a known skill's description. Call with action='list' to see available skills; call with action='load' and name=<skill> to activate one.",
+    "Load a project skill from .thincoder/skills/. Skills contain reusable instructions, workflows, or reference material. Use this when the user references a skill by name, or when a task matches a known skill's description. Call with action='list' to see available skills; call with action='load' and name=<skill> to activate one. " +
+    "Returns the skill list ('list'), the load confirmation ('load' — instructions arrive in the next message), or Error: ... with the available skills.",
   parameters: {
     type: "object",
     properties: {