@thincoder/core 0.9.1

package/agent-tools/parent-channel.mjs

@@ -0,0 +1,231 @@
+/**
+ * parent-channel.mjs — 子代理上行通道（子 → 父 在飞提问 / 上报）（批 SUBAGENT-UPSTREAM-CHANNEL；
+ * 设计权威 = `docs/core/design/AGENT-LOOP-SUBAGENT.md` §6.27；需求 = `docs/core/requirements/AGENT-LOOP.md` §4.12）。
+ *
+ * 补上子代理通信的第三象限：既有两象限 = 父→子在飞（`subagent action:'send'`）+ 子→父**终态**
+ * （报告 → settle → digest）；本档 = 子→父**在飞**——子代理运行中向父（spawn 方）发一条决策级
+ * 消息，**不中断自身回合**；父在**下一回合边界**合并消费，回复复用既有 `send`（零新下行管子）。
+ * F-UC7（2026-09-19 批 · §6.27.12）：ask 入队另**唤一次父侧挂起驱动**（`wakeAsyncWaiters`——
+ * 复用 W1 `_asyncWaiters` 通道）+ 三驱动第 2 步谓词 `upstreamWaiting` ⇒ 未 drain 的 ask 即刻
+ * 开轮注入——默认异步流下答复不再恒迟到（`note` 不唤醒：无时效义务）。
+ *
+ * 三面（§6.27.2/§6.27.4）：
+ * - 子侧发声 = 工具 `notify_parent`（**depth>0 专有**——`family-tools.mjs` depth>0 段装配，
+ *   consult / depth-0 不装配）；调用**同步返回**（零 await、零等待态——本档不提供任何拉取 /
+ *   轮询 / 等答复动作：D-UC3 非阻塞 = 结构保证）。
+ * - 父侧接收 = 队列 `_childUpstream`（数组；条目 `{seq, from, kind, message, ts}`）+ 单调计数
+ *   `_childUpstreamSeq`——**两字段皆属载体字段集**（AGENT-LOOP.md §2.3，与 `_asyncQueue` /
+ *   `_asyncAdvisorQueue` 同列）：读单点 = `async-settle.mjs` 的 `carrierField`，写单点 = 本档的
+ *   `upstreamHolder`（父字段优先 / `history` 命中即借用 / 皆无则建在父字段 + 载体别名）。
+ *   生命周期与子代理生命周期**解耦**（settle / cancel 不迁移、不清队列——F3）。
+ * - 父侧唤醒 = ask 入队尾调 `wakeAsyncWaiters(parent)`（**同步**，零 await；`note` 不唤醒）——
+ *   零新字段 / 零新容器 / 零新注册：等待栓数组由挂起驱动注册，非挂起期数组空 ⇒ no-op。
+ * - 父侧消费 = `drainChildUpstream(agent)`（`thincoder-core/agent.mjs` 循环头单点，紧邻
+ *   `consumeInjected?.(agent)`——同址反向）：全部 pending **合并一条** user 消息（`pushReal`
+ *   非 transient——事务性事件落盘，D-UC5），每条附结束注脚（已 settle / 已 cancel 两形态；
+ *   其余态不附——不臆断）。
+ *
+ * 三闸（可机判——§6.27.2 ③）：`kind` 枚举 `ask|note` · 同一子代理「未 drain」的 `ask` ≤
+ * `UPSTREAM_ASK_MAX_INFLIGHT`（窗口 = 父队列在场，drain 即关闭；机制面不追踪答复）· `message`
+ * ≤ `UPSTREAM_MSG_MAX` 且父队列 ≤ `UPSTREAM_QUEUE_MAX`（超限 = 工具**明确报错**，不静默丢）。
+ * 射程纪律（两问自检 + 正负清单）在提示词面（§6.27.8），机制面不新增语义判定。
+ *
+ * 模块图：静态 import 核单点 `async-settle.mjs`（`carrierField` / `getAsyncPool` /
+ * `tombstoneOf` / `wakeAsyncWaiters`——同层既有导出，同 `async-discard.mjs:35` 先例；唤醒走
+ * 既有静态边，零新增）+ `../context.mjs`（`pushReal`）
+ * / `../agent/helpers.mjs`（`escapeXml`）/ `../log.mjs`（`logEvent`）；单向、叶子向、无环。
+ * 登记册导出（`agent-tools.mjs`）→ 家族矩阵装配（`agent/family-tools.mjs` depth>0 段）。
+ */
+import { carrierField, getAsyncPool, tombstoneOf, wakeAsyncWaiters } from "./async-settle.mjs"
+import { pushReal } from "../context.mjs"
+import { escapeXml } from "../agent/helpers.mjs"
+import { logEvent } from "../log.mjs"
+
+/** message 长度上限（字符——闸三上界）。 */
+export const UPSTREAM_MSG_MAX = 1500
+/** 父队列总长上限（超 ⇒ 子侧工具明确报错——不静默丢）。 */
+export const UPSTREAM_QUEUE_MAX = 20
+/** 同一子代理「未 drain」的 ask 上限（窗口 = 父队列中存在本子代理的 ask 条目；drain 即关闭）。 */
+export const UPSTREAM_ASK_MAX_INFLIGHT = 1
+
+/** 工具返回注（异步形——sync: false；答复按普通指令在下回合边界到达）。 */
+const ASYNC_NOTE =
+  "delivered to your parent's queue — consumed at the parent's next turn boundary (non-blocking). " +
+  "Keep working on the unaffected parts; a reply arrives as an ordinary instruction at your next turn boundary. " +
+  "If your run ends first, report the unanswered part as not done."
+
+/** 工具返回注（同步形——`sync: true`：父阻塞在本次运行上 ⇒ **不给「答复到达」承诺**（F6））。 */
+const SYNC_NOTE =
+  "queued for your parent — but it spawned you synchronously and is blocked on this run, so no reply can reach you " +
+  "before you end. It reads this when its call returns and may re-spawn you; report the unanswered part as not done."
+
+/** 错误返回形（fail-closed——与 §6.7.2 / §6.25 的 status / observe / send 拒返回同款 JSON 对象形）。 */
+const refused = (error) => JSON.stringify({ status: "error", error })
+
+/**
+ * 写侧载体别名单点（§6.27.2 ① / §6.27.4）：`_childUpstream` / `_childUpstreamSeq` 的写恒经本
+ * 函数取容器（读恒经 `carrierField`——同两字段集）：
+ *   ① 父字段在场 ⇒ 父对象（CLI 形主容器——写侧不变）；
+ *   ② 缺 ⇒ `carrierField` 回退 `history` 命中 ⇒ **借用同一容器**（不另建分叉）；
+ *   ③ 两者皆无 ⇒ 建在父字段 + **载体别名**（`parent.history._childUpstream = parent._childUpstream`
+ *      ——同 `writeTombstone` 借用规则扩张句的既有形态，`agent-tools/async-settle.mjs:73-83`）。
+ */
+function upstreamHolder(parent) {
+  if (!Array.isArray(parent._childUpstream)) {
+    const existing = carrierField(parent, "_childUpstream")
+    if (Array.isArray(existing)) {
+      parent._childUpstream = existing // ② 借用（载体命中——同一容器）
+    } else {
+      parent._childUpstream = [] // ③ 主容器（父字段）
+      if (parent.history && typeof parent.history === "object") {
+        parent.history._childUpstream = parent._childUpstream // 载体别名（合成 parent 跨调用存活）
+      }
+    }
+  }
+  return parent
+}
+
+/**
+ * 父侧是否存在「未 drain 的 ask」（唤醒 / 开轮判据单点——三驱动第 2 步共用；载体经
+ * `carrierField` 吸收，与写侧 `upstreamHolder` 同口径）。容器缺省 / 非数组 ⇒ `false`
+ * （fail-closed——不抛）；`note` 不计（无时效义务——F13 语义零变）。
+ * @param {object} carrier 父（接收方）形态 / 载体对象。
+ * @returns {boolean}
+ */
+export function upstreamWaiting(carrier) {
+  const q = carrierField(carrier, "_childUpstream")
+  return Array.isArray(q) && q.some((e) => e.kind === "ask")
+}
+
+/**
+ * 子 → 父入队（单点；**同步**——零等待、零 await，非阻塞结构保证；`ask` 另同步唤一次父侧
+ * 挂起驱动〔`wakeAsyncWaiters`——无等待 / 无轮询，返回即达〕）。父侧下一回合边界由
+ * `drainChildUpstream` 合并消费；入队点直记 `child:upstream` 日志（消费点不另记）。
+ * @param {{parent: object, from: string, kind: "ask"|"note", message: string}} entry
+ * @returns {{seq: number, position: number}} position = 队列内 1-based 位次。
+ */
+export function pushChildUpstream({ parent, from, kind, message }) {
+  const holder = upstreamHolder(parent)
+  const seq = Number(carrierField(parent, "_childUpstreamSeq") ?? 0) + 1
+  holder._childUpstream.push({ seq, from, kind, message, ts: Date.now() })
+  holder._childUpstreamSeq = seq
+  logEvent("child:upstream", { id: from, kind, seq })
+  // §6.27.12.4 ① 唤醒（唯一激活点——入队 + 日志之后）：未 drain 的 ask 兑现父侧等待栓 ⇒
+  // 挂起驱动重入、第 2 步谓词开轮（唤醒 + 谓词两件一组，缺一无效）；note 不唤醒（避轮风暴）。
+  if (kind === "ask") wakeAsyncWaiters(parent)
+  return { seq, position: holder._childUpstream.length }
+}
+
+/**
+ * 结束注脚（drain 时读池状态——§6.27.4 表：两形态判据点 + 一显式不附注脚）：
+ * - 已 settle = 池内命中条目且 `entry.done === true`（done-in-pool 表示——§6.7.3）；
+ * - 已 cancel = 池**未命中** 且 `tombstoneOf(...).status === "cancelled"`（出池 + 墓碑）；
+ * - 其余态（`discarded` / `consumed` / `failed` 墓碑，或池与墓碑皆未命中）⇒ **不附注脚**
+ *   （消息本体照常注入——不臆断状态）。
+ * @returns {string} 注脚（含前导空格）或空串。
+ */
+function endNote(agent, entry) {
+  const id = String(entry.from).split("#").pop()
+  const inPool = getAsyncPool(agent, "subagent")?.get(String(id))
+  if (inPool?.done === true) return ` (${entry.from} has since settled — see its report)`
+  if (!inPool && tombstoneOf(agent, id)?.status === "cancelled") return ` (${entry.from} has since been cancelled)`
+  return ""
+}
+
+/**
+ * 父侧消费点（回合边界单点——`agent.mjs` 循环头；空队列 no-op = 零历史变更、零开销）：
+ * 全部 pending 消息**合并为一条** user 消息注入（`pushReal`——不带 `transient`，事件落盘），
+ * 按入队序逐条列示（来源 `role#id` + `kind` + message（`escapeXml`）+ 结束注脚）。
+ * @param {object} agent 父（消费方）agent 形态。
+ * @returns {number} 本次消费条目数（0 = 空队列 no-op）。
+ */
+export function drainChildUpstream(agent) {
+  const queue = carrierField(agent, "_childUpstream")
+  if (!Array.isArray(queue) || queue.length === 0) return 0
+  const entries = queue.splice(0) // 消费即清（单一消费者 = 回合边界）
+  const many = entries.length > 1
+  const header = many
+    ? `[System reminder: ${entries.length} in-flight message(s) from your subagents — they keep working on the unaffected parts. `
+      + "Answer with subagent action:'send' (id + message) if the decision is yours; an unanswered ask means that child skips the part and reports it as not done.]"
+    : `[System reminder: in-flight message from your subagent ${entries[0].from} — it keeps working on the unaffected parts. `
+      + "Answer with subagent action:'send' (id + message) if the decision is yours; an unanswered ask means the child skips that part and reports it as not done.]"
+  const rows = entries.map((e) => `${many ? "- " : ""}${e.kind} · ${e.from}: ${escapeXml(e.message)}${endNote(agent, e)}`)
+  pushReal(agent, { role: "user", content: [header, ...rows].join("\n") })
+  return entries.length
+}
+
+/**
+ * `notify_parent` — 子代理 → 父（spawn 方）单向通道（depth>0 专有）。
+ * 只读分类（同 `task` 工具判据「只改 agent 内部状态，不改外部世界」——`readonlyToolNames` 面：
+ * ① explore / plan 子代的只读过滤不剔本工具；② 权限门免 ask——子代理无交互 UI，explore / plan
+ * 的 childPermission 恒 false 会误拒；③ planMode / digest 面按只读放行）。
+ * `execute` 为**同步**函数（A4：工具 execute 无父侧 await——非阻塞结构保证的机判面）。
+ */
+export const parentChannelTool = {
+  name: "notify_parent",
+  description:
+    "A one-way channel to your PARENT (the agent that spawned you) — you are a subagent, so there is no user to ask.\n" +
+    "Queue a message on the parent's side; your turn is not interrupted and nothing is consumed from it.\n" +
+    "- kind:'ask' — a question whose answer changes your next step and that you cannot answer from the materials you can read\n" +
+    "  (task book / design doc / repo). The parent replies with subagent action:'send'; you receive it as an ordinary\n" +
+    "  instruction at your next turn boundary. One ask at a time while the previous one is still waiting in the parent's queue.\n" +
+    "- kind:'note' — an FYI that needs no answer (a premise you found broken, a conflict you resolved and want visible early).\n" +
+    "- NON-BLOCKING: the call returns immediately. Keep working on the unaffected parts; keep the affected part pending.\n" +
+    "  There is no fetch and no waiting — if you finish first, report the unanswered part as not done (never idle, never poll).\n" +
+    "- SYNCHRONOUS SPAWN: if the parent is blocked on your run (sync spawn), nothing can be sent back to you — the reply path (`send`) reaches only a RUNNING ASYNC child. The message is read when the parent's call returns (it may re-spawn you with an answer); report the unanswered part as not done.\n" +
+    "- Out of scope: naming / implementation / wording details, anything a read or a command would answer, trade-offs the\n" +
+    "  task book already states. When in doubt use the stop-and-report discipline — this is not an escape from your own judgment.\n" +
+    "- Availability: subagents only (depth > 0). At depth 0 you talk to the user through your normal reply or the question tool.",
+  parameters: {
+    type: "object",
+    properties: {
+      kind: {
+        type: "string",
+        enum: ["ask", "note"],
+        description: "ask = a question whose answer changes your next step; note = an FYI that needs no answer",
+      },
+      message: {
+        type: "string",
+        description: "The message to deliver to your parent (one short paragraph — details belong to your final report)",
+      },
+    },
+    required: ["kind", "message"],
+  },
+  readonly: true,
+  execute(args, ctx) {
+    // depth 门（execute 首行——§6.27.4）：本通道 depth>0 专有（depth-0 与用户的通道 = 普通回复 / question）。
+    if ((ctx?.depth ?? 0) === 0) {
+      return refused("notify_parent is only available inside a subagent (depth > 0) — at depth 0 you talk to the user through your normal reply or the question tool")
+    }
+    // 上游面（F7）：`_upstream` 由 spawn 站点装配（W1–W3）；缺失 = 未接线站点 ⇒ 明确报错（不静默成功）。
+    const upstream = ctx?.agent?._upstream
+    if (!upstream?.parent) {
+      return refused("notify_parent: this agent has no parent channel (not spawned through the subagent pipeline)")
+    }
+    const kind = args?.kind
+    if (kind !== "ask" && kind !== "note") {
+      return refused('notify_parent requires kind: "ask" (a question whose answer changes your next step) or "note" (an FYI that needs no answer)')
+    }
+    const message = typeof args?.message === "string" ? args.message.trim() : ""
+    if (!message) return refused("notify_parent requires a non-empty message")
+    if (message.length > UPSTREAM_MSG_MAX) {
+      return refused(`notify_parent message exceeds ${UPSTREAM_MSG_MAX} chars — one short paragraph; details belong to your final report`)
+    }
+    const { parent, label, sync } = upstream
+    const queue = carrierField(parent, "_childUpstream")
+    const pending = Array.isArray(queue) ? queue : []
+    // 闸二（窗口 = 「未 drain」——§6.27.2 ③）：本子代理的 ask 仍在父队列中 ⇒ 拒（不投递）。
+    if (kind === "ask") {
+      const mine = pending.filter((e) => e.from === label && e.kind === "ask")
+      if (mine.length >= UPSTREAM_ASK_MAX_INFLIGHT) {
+        return refused(`notify_parent: your earlier ask (#${mine[0].seq}) is still queued for your parent — one ask at a time until the parent picks it up; fold this into your final report if you cannot continue without an answer`)
+      }
+    }
+    // 闸三（父队列总长上限——超 ⇒ 报错，不静默丢）。
+    if (pending.length >= UPSTREAM_QUEUE_MAX) {
+      return refused(`notify_parent: the parent's in-flight queue is full (${UPSTREAM_QUEUE_MAX}) — the parent has not consumed the pending messages yet; fold yours into your final report instead`)
+    }
+    const { position } = pushChildUpstream({ parent, from: label, kind, message })
+    return JSON.stringify({ status: "queued", kind, position, note: sync === true ? SYNC_NOTE : ASYNC_NOTE })
+  },
+}

package/agent-tools/plan.mjs

@@ -0,0 +1,86 @@
+/**
+ * plan tool: enter/exit plan mode.
+ * In plan mode only read-only tools are allowed — explore code, design solutions, no code writing.
+ * After the user approves the plan, exit plan mode and start implementing.
+ *
+ * Reminder cadence (kimi-code style): while plan mode is active the agent loop
+ * re-injects reminders — sparse every 2 turns, full every 5 turns or when the
+ * user sends a new message — so the constraint never fades from context.
+ */
+
+const PLAN_FULL_REMINDER =
+  "[System reminder: plan mode is ON. Workflow: (1) explore/read codebase with read-only tools, " +
+  "(2) design a solution considering trade-offs, (3) present your plan by calling plan with action='exit' " +
+  "so the user can approve it. Only read-only tools are allowed — do not write, edit, or run mutation commands. " +
+  "Your turn must end with either a clarifying question to the user or a call to plan with action='exit'.]"
+
+const PLAN_SPARSE_REMINDER =
+  "[System reminder: plan mode still active — read-only tools only (the current plan file exempt). " +
+  "Design the solution, then call plan with action='exit' for user approval.]"
+
+const PLAN_EXIT_REMINDER =
+  "[System reminder: plan mode is now OFF. Start implementing your plan — edit files, run commands. " +
+  "No need for a task list (plan already covered that) or further confirmation.]"
+
+/** Turns between reminder re-injections while plan mode is active */
+const SPARSE_INTERVAL = 2
+const FULL_INTERVAL = 5
+
+/**
+ * Decide which plan-mode reminder (if any) to inject this turn.
+ * @param {object} agent — the agent object (mutated: tracks reminder state)
+ * @param {boolean} userMessageSince — whether a user message arrived since the last reminder
+ * @returns {string|null} reminder text or null
+ */
+export function planReminderForTurn(agent, userMessageSince) {
+  if (!agent.planMode) {
+    agent._planTurnsSinceReminder = 0
+    agent._planTurnsSinceSparse = 0
+    return null
+  }
+  agent._planTurnsSinceReminder = (agent._planTurnsSinceReminder ?? 0) + 1
+  agent._planTurnsSinceSparse = (agent._planTurnsSinceSparse ?? 0) + 1
+  if (userMessageSince || agent._planTurnsSinceReminder >= FULL_INTERVAL) {
+    agent._planTurnsSinceReminder = 0
+    agent._planTurnsSinceSparse = 0
+    return PLAN_FULL_REMINDER
+  }
+  if (agent._planTurnsSinceSparse >= SPARSE_INTERVAL) {
+    agent._planTurnsSinceSparse = 0
+    return PLAN_SPARSE_REMINDER
+  }
+  return null
+}
+
+export const planTool = {
+  name: "plan",
+  description:
+    "Enter or exit plan mode. In plan mode you are restricted to READ-ONLY tools: read files, search code, run read-only shell commands. Use plan mode before complex multi-step tasks — explore the codebase, design the architecture, present a plan to the user. When the user approves, exit plan mode and implement. For simple single-file edits, skip plan mode and just make the change.",
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["enter", "exit"], description: "Enter or exit plan mode" },
+    },
+    required: ["action"],
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    // §2.5 #85（已裁 · 以 VSC 为准）：未知 action 明确报错——旧行为（非 exit 一律进 plan
+    // 模式）把拼错的 action 当成 enter，静默改写会话状态。
+    if (args.action === "exit") {
+      ctx.agent.planMode = false
+      ctx.agent._planTurnsSinceReminder = 0
+      ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
+      ctx.agent._pendingReminders.push(PLAN_EXIT_REMINDER)
+      return "Plan mode exited. You may now edit files and run commands."
+    }
+    if (args.action !== "enter") {
+      return `Error: unknown action "${args.action}". Use "enter" or "exit".`
+    }
+    ctx.agent.planMode = true
+    ctx.agent._planTurnsSinceReminder = 0
+    ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
+    ctx.agent._pendingReminders.push(PLAN_FULL_REMINDER)
+    return "Plan mode activated. You are now restricted to READ-ONLY tools. Explore the codebase, understand the architecture, design a solution. Present your plan to the user for approval before writing any code."
+  },
+}

package/agent-tools/read-history.mjs

@@ -0,0 +1,309 @@
+/**
+ * agent-tools/read-history.mjs — read_history tool (SESSION.md §6.9 + §6.13 R19 cross-session).
+ *
+ * Query message history — THIS session by default, any session on disk with `path`
+ * (SESSION.md §6.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 (record store when bound
+ * — disk-backed, SESSION.md §6.14; agent._fullHistory memory fallback otherwise:
+ * 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).
+ *
+ * Cross-session (SESSION.md §6.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)
+ * plus a message-count cap (READ_HISTORY_MAX_MESSAGES = 50,000 — L24 双保险第二道).
+ *
+ * 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 §6.9 refinement 1 + §6.13 T-R19.4).
+ * §6.13 R19 extension mirrored per SESSION.md §6.13 — double-end isomorphic, no
+ * cross-end byte test (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 §6.13 D-R19a——评审 #3 定稿：超限不再读全文，返回定稿错误文案）。 */
+export const READ_HISTORY_SCAN_MAX = 200_000
+
+/** L24 消息数预算（评审 #2 钉死——双保险第二道）：行扫按物理 \n 行计——JSON 单行槽
+ *  行扫不设防——parse 后 history 数组长度超限即拒（同款定稿文案——双端同常量同文案）。 */
+export const READ_HISTORY_MAX_MESSAGES = 50_000
+
+/** 超限错误文案（SESSION.md §6.13——逐字定稿——T-R19.7 断言）。 */
+const TOO_LARGE_ERROR = JSON.stringify({ error: "session too large — refine keyword or since/until" })
+
+/** 检索/记忆族消歧总纲（SESSION.md §6.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
+  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
+}
+
+/** AND-filter one history message (role/keyword/tool/since-until) — shared by the in-memory
+ *  default and the cross-session file query (SESSION.md §6.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 §6.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 (§6.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)`
+  }
+  if (data.history.length > READ_HISTORY_MAX_MESSAGES) {
+    // L24 消息数第二道（parse 后——行扫按物理行、单行 JSON 槽行扫不设防——超限同款拒绝）。
+    return TOO_LARGE_ERROR
+  }
+  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（§6.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 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. " +
+    "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 50,000 messages or 200,000 lines is refused (\"session too large\") instead of being read whole.\n" +
+    SEARCH_FAMILY_GUIDE,
+  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)." },
+      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`
+    }
+    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 (绑定态存储行 = slimForDisplay 产物——匹配基准 delta 见 SESSION.md
+    // §6.14 / T-RS8b) — 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 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)
+    }
+
+    // 本会话（无 path）：绑定记录存储 → 方向流式迭代（磁盘为准——全量可见、内存窗口外
+    // 可命中；§6.14）；未绑定（测试 / 模式 F）→ 内存 _fullHistory 既有过滤路径（回退保留）。
+    // 方向语义不变：newest 自尾向前取满 limit → 反转回时间序（输出恒时间序）。
+    const store = ctx.agent?._recordStore
+    if (store?.iterate) {
+      const taken = []
+      for (const m of store.iterate(direction)) {
+        if (!matches(m, { role, kwRe, tool, since, until })) continue
+        taken.push(m)
+        if (taken.length >= limit) break
+      }
+      return formatMatches(direction === "newest" ? taken.reverse() : taken, "oldest", limit)
+    }
+    const history = Array.isArray(ctx.agent?._fullHistory) ? ctx.agent._fullHistory : []
+    const matched = history.filter((m) => matches(m, { role, kwRe, tool, since, until }))
+    return formatMatches(matched, direction, limit)
+  },
+}

package/agent-tools/recent-changes.mjs

@@ -0,0 +1,24 @@
+/**
+ * recent_changes tool: list files touched by this agent run (write/edit/insert_after/delete).
+ * More precise than git status — only looks at this session's changes, independent of git tracking.
+ * Helps the model recall what it already modified during long tasks.
+ */
+export const recentChangesTool = {
+  name: "recent_changes",
+  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. " +
+    "For session-level history (what was said in a session), use read_history.",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  readonly: true,
+  execute(args, ctx) {
+    const files = ctx.agent._touchedFiles ?? []
+    if (files.length === 0) return "(no files modified in this run yet)"
+    const deduped = [...new Set(files)]
+    return `Touched ${deduped.length} file(s) this run:\n${deduped.join("\n")}`
+  },
+}