thincoder 0.12.59 → 0.12.60

package/src/agent-tools/escalate-async.mjs

@@ -0,0 +1,286 @@
+/**
+ * escalate-async.mjs — async 飞刀 runner (AGENT-LOOP.md §25 D-R17b — R17, 2026-09-06).
+ *
+ * The subagent action:"escalate" is DEFAULT-async at depth 0 (decision ③: the
+ * depth-0-only escalate flips to async like every other background family;
+ * `async: false` keeps the legacy synchronous flight). An async escalate runs in
+ * the SHARED "other" pool domain (decision Q2 🅰 — the entry lives in
+ * `_asyncSubagents` with role "escalate"/_pool "other", so it shares the 4-slot
+ * other domain with explore/plan/coder spawns — capacity, queueing, refill,
+ * status and cancel all come from the generic machinery):
+ * - launch → ack {id, role:"escalate", status:"running"|"queued"[, position]};
+ *   the turn ends naturally, the session suspends (poolLive counts the entry).
+ * - settle THREE-WAY classification (review #4): done → merge-all mutations back
+ *   into the parent's bookkeeping + overlap warning appended to the report
+ *   (report-level, not a gate — round2 #4); error (child failure / turn cap) →
+ *   partial mutations merged ONLY when the parent did not touch overlapping
+ *   files since launch (overlap → no merge + differences listed in the report);
+ *   cancelled → never reaches the digest stream (D-M6 — no merge, stopped
+ *   reminder).
+ * - the classified report lands in `_pendingAsyncResults`（pending 单容器 +role——
+ *   ASYNC-RESULT-CONTAINER.md D2——挂起期 settle 移交）when the settle happens in a
+ *   suspension, or stays pooled for the turn-end collection otherwise;
+ *   injectAsyncResult's escalate
+ *   role branch delivers the digest ("报告已 merge——可继续处置" — the action
+ *   domain still follows the consuming turn's tier — no family exception).
+ */
+import { relative, isAbsolute } from "node:path"
+import { runAgent, createAgent, CODER_OVERLAY, DEFAULT_SUBAGENT_TURNS } from "../agent.mjs"
+import { runWithContinue, TURN_CAP_MARK, wrapChildCallbacks } from "../agent/spawn-child.mjs"
+import { logEvent } from "../log.mjs"
+import {
+  mergeChildMutations, runningPoolCount, poolDomainOf, poolLimitsFor, ASYNC_POOL_LIMITS,
+} from "./subagent-async.mjs"
+import { refreshQueuedTokens } from "./subagent-scheduler.mjs"
+import { mutationSeqOf } from "./advisor-async.mjs"
+// ASYNC-RESULT-CONTAINER.md D3/D6：settle 公共收尾单点 + child signal 构建单点
+import { buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
+
+/** Parent-side mutations (absolute paths) committed AFTER the escalate launch —
+ *  the overlap scan feeds the settle classification (review #4/round2 #4: the
+ *  parent may have edited files while the flight ran). */
+function parentMutationsSince(parent, launchSeq) {
+  const out = []
+  for (const m of parent?._mutLog ?? []) {
+    if (m.seq <= (launchSeq ?? -1)) continue
+    for (const p of m.paths ?? []) if (!out.includes(p)) out.push(p)
+  }
+  return out
+}
+
+/** Files BOTH sides touched since launch (case-insensitive key on win32 —
+ *  filesOverlap precedent). */
+function overlapPaths(parent, launchSeq, childTouched) {
+  const since = parentMutationsSince(parent, launchSeq)
+  if (since.length === 0 || !childTouched?.length) return []
+  const key = (p) => (process.platform === "win32" ? String(p).toLowerCase() : String(p))
+  const sinceKeys = new Set(since.map(key))
+  const hits = childTouched.filter((p) => sinceKeys.has(key(p)))
+  // relative display form (touchedFilesNote precedent)
+  const cwd = parent?.cwd ?? process.cwd()
+  return hits.map((p) => {
+    const r = relative(cwd, p)
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : p
+  })
+}
+
+/** Escalate-side touched files, relative display (or a placeholder). */
+function childTouchedDisplay(child, cwd) {
+  const touched = child?._touchedFiles ?? []
+  if (touched.length === 0) return "(none recorded)"
+  const shown = touched.map((f) => {
+    const r = relative(cwd ?? process.cwd(), f)
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : f
+  })
+  return shown.join(", ")
+}
+
+/** Relative touched-file list (mirror of the sync path's note). */
+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(", ")}`
+}
+
+/**
+ * Async escalate settle — three-way classification (§25 D-R17b review #4):
+ *  - done: merge ALL mutations (the escalation's changes are the parent's —
+ *    verify/advisor guards must see them) + overlap warning into the report
+ *    (report-level hint — not a gate — round2 #4);
+ *  - error (child failure / turn cap): partial mutations merge ONLY without a
+ *    parent-side overlap — overlap → NO merge + differences listed (the report
+ *    carries both sides so the model can decide);
+ *  - cancelled: nothing merges, never reaches pending (D-M6 — stopped reminder).
+ * Runs BEFORE the pending transfer / digest injection. Mutates entry.report /
+ * entry.error into the FINAL digest body (the family wording rides
+ * injectAsyncResult's escalate branch).
+ */
+export function classifyEscalateSettle(parent, entry) {
+  if (entry.cancelled) return { cancelled: true }
+  const child = entry.childAgent
+  const touched = child?._touchedFiles ?? []
+  const overlap = overlapPaths(parent, entry.launchSeq, touched)
+  const hasError = entry.error != null
+  const raw = hasError ? entry.error : entry.report
+  if (hasError) {
+    // error branch (child failure / turn cap — review #4): partial mutations
+    // merge ONLY when the parent did not touch overlapping files since launch.
+    // childAgent may be null when the flight died before child creation (advisor
+    // 复评 🟡2——防御：无 child 即无 partial mutations——不 merge 不崩）。
+    const merged = child != null && overlap.length === 0 && mergeChildMutations(parent, child)
+    let decision = ""
+    if (merged) {
+      decision = `\nPartial changes merged into the parent's bookkeeping (no parent-side overlap since launch).`
+    } else if (overlap.length > 0) {
+      decision = `\nPartial changes NOT merged — the parent changed overlapping files while this escalate ran: ${overlap.join(", ")}. Escalate-side changes: ${childTouchedDisplay(child, parent?.cwd)}. Review the conflict and decide what to keep (report-level — not a gate; AGENT-LOOP.md §25 D-R17b).`
+    }
+    // (nothing to merge + no overlap → the plain error report stands alone)
+    entry.error = `${raw}${decision}`
+    entry.report = null
+    return { cancelled: false, merged, overlap }
+  }
+  // done — merge-all + overlap warning into the report (report-level — not a gate)
+  const merged = mergeChildMutations(parent, child)
+  const overlapNote = overlap.length > 0
+    ? `\n⚠ Overlapping writes: the parent changed ${overlap.join(", ")} while this escalate ran — mutations merged all the same; review those files before building on the report (report-level warning — not a gate; AGENT-LOOP.md §25 D-R17b round2 #4).`
+    : ""
+  entry.report = `${raw}${overlapNote}`
+  return { cancelled: false, merged, overlap }
+}
+
+/**
+ * Launch the async escalate (preflights already passed in executeEscalateAction):
+ * pool admission into the shared OTHER domain → entry in `_asyncSubagents`
+ * (generic queue/refill/status/cancel machinery) → ack. The flight starts on
+ * entry.start() (immediately, or later via maybeRefillAsync when a slot frees).
+ */
+export function launchEscalateAsync(parent, ctx, launch) {
+  const { task, provider, tag, effortNote } = launch
+  parent._asyncSubagents ??= new Map()
+  parent._asyncQueue ??= []
+  // Async id allocation (AGENT-LOOP.md §15 D-A1 precedent): reserve the relay
+  // counter at launch — the returned id stays stable while the entry sits queued.
+  // The [model] token (TUI block creation) is DEFERRED to actual start so queued
+  // flights don't paint an empty panel block (subagent-parity).
+  parent._subAgentCounter = (parent._subAgentCounter ?? 0) + 1
+  const relayPrefix = `escalate#${parent._subAgentCounter}/`
+  const id = parent._subAgentCounter
+  const entry = {
+    id, role: "escalate", relayPrefix,
+    _pool: poolDomainOf("escalate"), // other — shares the domain with explore/plan/coder (§24 D-24a)
+    status: "queued",
+    position: undefined,
+    report: null, error: null, done: false, cancelled: false,
+    promise: null, _settle: null, _settleSeq: 0,
+    model: provider.model ?? null,
+    startedAt: null,
+    turn: 0, maxTurns: 0,
+    controller: null,
+    _files: undefined, _dependsOn: undefined,
+    childAgent: null,
+    tag, effortNote, launchSeq: mutationSeqOf(parent),
+  }
+  const limits = poolLimitsFor(parent)
+  entry.status = runningPoolCount(parent, entry._pool) >= (limits[entry._pool] ?? ASYNC_POOL_LIMITS[entry._pool])
+    ? "queued" : "running"
+  entry.promise = new Promise((res) => { entry._settle = res })
+  const ctrl = new AbortController()
+  entry.controller = ctrl
+  // D6 buildChildSignal 单点（ASYNC-RESULT-CONTAINER.md——D5 同款：_sessionSignal 兜底）。
+  const baseSignal = buildChildSignal(parent, ctx)
+  if (baseSignal) {
+    if (baseSignal.aborted) ctrl.abort()
+    else baseSignal.addEventListener("abort", () => ctrl.abort(), { once: true })
+  }
+  // Turn mirror (⟦ev⟧turn from the child runAgent → entry.turn/maxTurns — status parity).
+  const flight = async () => {
+    entry.status = "running"
+    entry.position = undefined
+    entry.startedAt = Date.now()
+    ctx.callbacks?.onToken?.(relayPrefix + "⟦ev⟧async\x1e")
+    ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (provider.model ?? ""))
+    const child = createAgent({
+      provider,
+      tools: parent.tools,
+      config: parent.config,
+      cwd: parent.cwd,
+      memory: parent.memory,
+      overlay: CODER_OVERLAY,
+      role: "coder",
+    })
+    entry.childAgent = child // settle 分类/status touched 摘要绑定（start 时刻）
+    child._logId = relayPrefix.slice(0, -1)
+    logEvent("child:spawn", { role: "escalate", id: child._logId, kind: "async", status: "running", ms: 0 })
+    const childCallbacks = wrapChildCallbacks(relayPrefix, ctx.callbacks ?? {})
+    const relayOnToken = childCallbacks.onToken
+    if (relayOnToken) {
+      childCallbacks.onToken = (t) => {
+        const ev = String(t).match(/^⟦ev⟧turn\x1e(\d+)\x1e(\d+)\x1e/)
+        if (ev) {
+          entry.turn = Number(ev[1]) || 0
+          entry.maxTurns = Number(ev[2]) || 0
+        }
+        return relayOnToken(t)
+      }
+    }
+    const runner = ctx.runAgent ?? runAgent
+    const runOpts = {
+      depth: 1,
+      maxTurns: parent.config?.agent?.subagentTurns ?? DEFAULT_SUBAGENT_TURNS,
+      signal: entry.controller.signal,
+    }
+    // 权限按 async 子代理同款装配：AUTO 直放行；手动档经父 _permQueue（并行子代理
+    // 审批不叠弹窗）——背景飞行撞门时无 handler → denied 不悬挂（D-S7 同规则）。
+    const childPermission = parent.autoApprove
+      ? async () => true
+      : async (name, toolArgs) => {
+          if (!ctx.onPermissionRequest) return false
+          const ask = () => ctx.onPermissionRequest(`escalate/${name}`, toolArgs)
+          parent._permQueue = (parent._permQueue ?? Promise.resolve()).then(ask, ask)
+          return parent._permQueue
+        }
+    const report = await runWithContinue(
+      (childAgent, input, cbs, opts) => runner(childAgent, input, cbs, opts),
+      child, task,
+      { ...childCallbacks, onPermissionRequest: childPermission },
+      runOpts,
+      {
+        // 后台飞行不弹 continue 面板（D-A3 §15 例外同款）：AUTO && engineering 自动
+        // resume——escalate 只在 normal 模式可用（engineering 拒）——恒自动拒 → partial。
+        askContinue: () => Promise.resolve(Boolean(parent.config?.agent?.engineering && parent.autoApprove)),
+        onDeclined: (e, output) => `escalate (${tag})${entry.effortNote} ${TURN_CAP_MARK} (${e.turn} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${output.slice(0, 2000)}`,
+      },
+    )
+    // done: compose the post-op body (the settle classification appends the
+    // overlap warning / merge notes afterwards)
+    return `escalate (${tag})${entry.effortNote} post-op report:\n${report || (child._capturedOutput ?? "").slice(0, 4000)}${touchedFilesNote(child, parent.cwd)}`
+  }
+  entry.start = () => {
+    flight()
+      .then((report) => {
+        // Turn-cap partial (runWithContinue auto-declined) classifies as the ERROR
+        // branch (design: 撞 turn cap = error — partial-merge decision applies):
+        // move it to entry.error so the classification + error digest wording fire.
+        if (String(report).includes(TURN_CAP_MARK)) entry.error = report
+        else entry.report = report
+      })
+      .catch((e) => {
+        // 运行失败/中止：错误文本落 entry.error（子代理同款——cancel 分支忽略它；
+        // Ctrl+I 中止的残条目由收尾消化带错误文本——不落空 "(no report)" digest）。
+        const child = entry.childAgent
+        entry.error = `escalate (${tag}) error: ${e?.message ?? String(e)}\nPartial output: ${(child?._capturedOutput ?? "").slice(0, 2000)}`
+      })
+      .finally(() => {
+        // settle 公共收尾单点（ASYNC-RESULT-CONTAINER.md D3——settleAsyncEntry）：日志三连
+        // /cancelled 分支（出池+墓碑+⟦ev⟧stopped+提醒）/挂起分流（pending 单容器+出池——
+        // 统一守卫 !parentAborted——D4）/公共尾部（settleSeq/_settle/唤醒 waiter + 腾槽补位
+        // ——helper 尾部恒补）统一走共享 helper。族特有 hook = 三分类 merge 决策
+        // （classifyEscalateSettle——done/error 分类；cancelled 不经此——helper cancelled
+        // 分支先行）。
+        settleAsyncEntry(parent, entry, {
+          pool: parent._asyncSubagents,
+          ctx,
+          onAccounting: () => {
+            // Three-way settle classification (done/error/cancelled — review #4)：
+            // done → merge-all + 重叠警告；error → 无父侧重叠才 partial merge；
+            // cancelled 不经此（helper cancelled 分支先行）。
+            void classifyEscalateSettle(parent, entry)
+          },
+        })
+      })
+  }
+  parent._asyncSubagents.set(String(id), entry)
+  logEvent("child:spawn", { role: "escalate", id: `escalate#${id}`, kind: "async", status: entry.status, ms: 0 })
+  if (entry.status === "queued") {
+    parent._asyncQueue.push(entry)
+    entry.position = parent._asyncQueue.length
+    refreshQueuedTokens(parent, ctx.callbacks?.onToken)
+    return JSON.stringify({ id: String(id), role: "escalate", status: "queued", position: entry.position })
+  }
+  entry.start()
+  return JSON.stringify({ id: String(id), role: "escalate", status: "running" })
+}

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

@@ -1,9 +1,13 @@
 /**
- * agent-tools/read-history.mjs — read_history tool (SESSION.md §9).
+ * agent-tools/read-history.mjs — read_history tool (SESSION.md §9 + §13 R19 cross-session).
  *
- * 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.
+ * Query message history — THIS session by default, any session on disk with `path`
+ * (SESSION.md §13 R19): an explicit session file path deep-queries that file's
+ * history line; "cwd:<dir>" discovers the sessions stored for that directory.
+ *
+ * Default (no path) — THIS session's 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
@@ -17,17 +21,38 @@
  * session file. assistant tool_calls are summarized to a name list (arguments
  * never expanded).
  *
+ * Cross-session (SESSION.md §13 D-R19a): path = a session file path (absolute, or
+ * relative to the project cwd) → read that file's history line and apply the SAME
+ * filter surface; path = "cwd:<dir>" → list every slot stored for that directory
+ * (slot number + full file path + title/message count/updatedAt — no dead-slot
+ * filtering, v1 decision). Single-file retrieval is guarded by a line-scan cap
+ * (READ_HISTORY_SCAN_MAX) — an oversized file is refused before it is read whole.
+ *
  * 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).
+ * child would be semantically confusing (SESSION.md §9.5 refinement 1 + §13 T-R19.4).
  * Mirrored 1:1 in thincoder-vscode/src/agent-tools/read-history.mjs.
  */
 
+import { openSync, readSync, closeSync, readFileSync, existsSync, statSync } from "node:fs"
+import { isAbsolute, resolve } from "node:path"
+import { listSlots, slotPath } from "../session-slots.mjs"
+
 const DEFAULT_LIMIT = 50
 const MAX_LIMIT = 200
 const CONTENT_CAP = 500
 const VALID_ROLES = new Set(["user", "assistant", "tool"])
 
+/** 单槽检索行扫护栏（SESSION.md §13 D-R19a——评审 #3 定稿：超限不再读全文，返回定稿错误文案）。 */
+export const READ_HISTORY_SCAN_MAX = 200_000
+
+/** 超限错误文案（SESSION.md §13——逐字定稿——T-R19.7 断言）。 */
+const TOO_LARGE_ERROR = JSON.stringify({ error: "session too large — refine keyword or since/until" })
+
+/** 检索/记忆族消歧总纲（SESSION.md §13 D-R19b——逐字定稿——read_history 描述尾段——T-R19.5 锚）。 */
+const SEARCH_FAMILY_GUIDE =
+  "检索/记忆族选哪个：查**本会话**说过/裁定过 → read_history（默认）；查**别的会话/项目**旧对话 → read_history 带 path/cwd 参数；查**本 run 改过哪些文件** → recent_changes；查**跨会话已存知识/约定**（memory）→ memory search；查**项目设计文档** → doc_search；查**代码实现** → code_search；查 git 历史快照 → checkpoint cat/versions。read_history 只查会话消息——文件级改动用 recent_changes——知识与约定用 memory——互相不替代。"
+
 /** 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
@@ -80,17 +105,125 @@ function toEntry(m) {
   return entry
 }
 
+/** AND-filter one history message (role/keyword/tool/since-until) — shared by the in-memory
+ *  default and the cross-session file query (SESSION.md §13 D-R19a: 同 filter 面应用). */
+function matches(m, { role, kwRe, tool, since, until }) {
+  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. */
+function formatMatches(matched, direction, limit) {
+  const windowed = direction === "oldest" ? matched.slice(0, limit) : matched.slice(-limit)
+  return JSON.stringify(windowed.map(toEntry))
+}
+
+/** Line-scan guard: stream-count physical newlines, bailing the moment the cap is crossed —
+ *  an oversized file is refused BEFORE it is read whole ("不再读全文"——SESSION.md §13 D-R19a). */
+function exceedsScanMax(file) {
+  const CHUNK = 64 * 1024
+  let fd = null
+  try {
+    fd = openSync(file, "r")
+    const buf = Buffer.alloc(CHUNK)
+    let newlines = 0
+    for (;;) {
+      const n = readSync(fd, buf, 0, CHUNK, null)
+      if (n <= 0) break
+      for (let i = 0; i < n; i++) {
+        if (buf[i] === 0x0a) newlines++
+      }
+      if (newlines > READ_HISTORY_SCAN_MAX) return true
+    }
+    return false
+  } catch {
+    return false // 行扫失败 → 交由后续读取/解析路径给出真实错误
+  } finally {
+    if (fd !== null) {
+      try { closeSync(fd) } catch { /* ignore */ }
+    }
+  }
+}
+
+/** Cross-session deep query: one session file, same filter surface (§13 D-R19a). */
+function querySessionFile(pathArg, { role, kwRe, tool, since, until, direction, limit }, baseCwd) {
+  const file = isAbsolute(pathArg) ? pathArg : resolve(baseCwd ?? process.cwd(), pathArg)
+  if (!existsSync(file)) return `Error: session file not found: ${file}`
+  if (exceedsScanMax(file)) return TOO_LARGE_ERROR
+  let text
+  try {
+    text = readFileSync(file, "utf8")
+  } catch (e) {
+    return `Error: failed to read session file ${file}: ${e.message}`
+  }
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch (e) {
+    return `Error: ${file} is not a valid session file (corrupt JSON: ${e.message})`
+  }
+  if (!data || typeof data !== "object" || !Array.isArray(data.history)) {
+    return `Error: ${file} is not a valid session file (no history array)`
+  }
+  const matched = data.history.filter((m) => matches(m, { role, kwRe, tool, since, until }))
+  return formatMatches(matched, direction, limit)
+}
+
+/** Discovery surface (path = "cwd:<dir>"): list every slot stored for that directory, one line
+ *  per slot — slot number + FULL session file path + title/message count/updatedAt（§13 D-R19a
+ *  ——评审 #2：摘要必须含寻址字段——模型第二步深查 = 复制行内文件路径重调 path=）。 */
+function discoverCwd(raw, baseCwd) {
+  const dir = resolve(baseCwd ?? process.cwd(), raw)
+  let st = null
+  try {
+    st = statSync(dir)
+  } catch { /* fallthrough to the explicit error below */ }
+  if (st === null || !st.isDirectory()) {
+    return `Error: unknown cwd "${raw}" — no session directory for this cwd (directory not found: ${dir})`
+  }
+  const slots = listSlots(dir) // 时间序（updatedAt 降序）——含 manifest 记录的全部槽（v1 不做死槽过滤）
+  if (slots.length === 0) {
+    return `(no session slots found for cwd: ${dir} — no sessions started there yet)`
+  }
+  const lines = slots.map((s) => {
+    const title = s.title ? `"${s.title}"` : "(untitled)"
+    return `slot ${s.slot}: ${slotPath(dir, s.slot)} — title: ${title}, messages: ${s.messageCount}, updatedAt: ${s.updatedAt}`
+  })
+  return `Session slots for cwd: ${dir} (newest first):\n${lines.join("\n")}`
+}
+
 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. " +
+    "Query message history — THIS session by default, any session on disk with `path`. " +
+    "Default (no path): THIS session's full record (never compacted, audit-complete) — 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.",
+    "Cross-session (path, optional): a session file path deep-queries THAT session's history with the same filters " +
+    "(relative paths resolve against the project cwd); \"cwd:<dir>\" lists every session slot stored for that directory — " +
+    "one line per slot: slot number + full session file path + title + message count + updatedAt; copy a listed file path into path= to deep-query it. " +
+    "A session file over 200,000 lines is refused (\"session too large\") instead of being read whole.\n" +
+    SEARCH_FAMILY_GUIDE,
   parameters: {
     type: "object",
     properties: {
@@ -101,11 +234,15 @@ export const readHistoryTool = {
       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)." },
+      path: { type: "string", description: "Optional — query another session instead of this one: a session file path (as listed by a \"cwd:<dir>\" call) deep-queries that session; \"cwd:<dir>\" lists that directory's session slots (slot number + full file path + title + message count + updatedAt)." },
     },
   },
   readonly: true,
   execute(args, ctx) {
     const a = args ?? {}
+    if (a.path !== undefined && (typeof a.path !== "string" || a.path.trim().length === 0)) {
+      return `Error: invalid path "${a.path}" — must be a session file path or "cwd:<dir>"`
+    }
     const role = a.role
     if (role !== undefined && (typeof role !== "string" || !VALID_ROLES.has(role))) {
       return `Error: invalid role "${role}" — valid roles: user, assistant, tool`
@@ -131,30 +268,17 @@ export const readHistoryTool = {
     // 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 baseCwd = ctx.agent?.cwd ?? process.cwd()
+
+    const pathArg = typeof a.path === "string" && a.path.trim().length > 0 ? a.path.trim() : null
+    if (pathArg !== null) {
+      return pathArg.startsWith("cwd:")
+        ? discoverCwd(pathArg.slice("cwd:".length), baseCwd)
+        : querySessionFile(pathArg, { role, kwRe, tool, since, until, direction, limit }, baseCwd)
+    }
 
     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))
+    const matched = history.filter((m) => matches(m, { role, kwRe, tool, since, until }))
+    return formatMatches(matched, direction, limit)
   },
 }

package/src/agent-tools/recent-changes.mjs

@@ -8,7 +8,8 @@ export const recentChangesTool = {
   description:
     "Show files modified in this agent run (write/edit/insert_after/delete). " +
     "Use when you need to remember which files you've already touched — during long multi-file tasks, " +
-    "it's easy to lose track. This is scoped to the current run, unlike git status which shows all uncommitted changes.",
+    "it's easy to lose track. This is scoped to the current run, unlike git status which shows all uncommitted changes. " +
+    "For session-level history (what was said in a session), use read_history.",
   parameters: {
     type: "object",
     properties: {},

package/src/agent-tools/settings.mjs

@@ -7,9 +7,7 @@
  * （••••（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"
+import { DEFAULTS, configPath, writeConfigAtomic } from "../config.mjs"
 
 /** 敏感键段判定（完整点分路径的段级匹配——apiKey/api_key/api-key/token/secret/password 形态） */
 const SENSITIVE_SEGMENT = /(^|[._-])(api[_-]?key|key|token|secret|password)($|[._-])/i
@@ -91,16 +89,6 @@ function parseValue(raw) {
 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:
@@ -150,10 +138,12 @@ export function settingsTool(opts = {}) {
           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)
+      // 写盘（D-F5b：磁盘真相最小化——writeConfigAtomic 磁盘新鲜读 + 只改被设键 + mtime
+      // 门控——默认不固化；冲突/畸形抛错，内存不热应用（零虚假成功））+ 热应用（内存对象）
+      const r = await writeConfigAtomic(cfgPath, (disk) => {
+        setKeyPath(disk, args.key, value)
+      })
+      if (!r.ok) throw new Error("config changed on disk concurrently — retry (settings set not applied)")
       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（运行中已生效）"}`