@zhushanwen/pi-session-reader 0.3.0 → 0.4.0

package/src/__tests__/workflow.test.ts

@@ -151,6 +151,33 @@ describe('parseRunSnapshot', () => {
     expect(overview!.steps[1].contentPreview).toBe('OK')
   })
 
+  it('TC-w5-parse-new-status-unknown：NEW call.status 非 done/running/pending（如 failed）→ step.status=pending', () => {
+    // call.status 出现三态外的值（如上游异常态）时收窄为 pending，其余字段照常提取
+    const fixture = {
+      ...NEW_SNAPSHOT_FIXTURE,
+      state: {
+        ...NEW_SNAPSHOT_FIXTURE.state,
+        calls: [
+          {
+            id: 3,
+            opts: { description: 'step-3' },
+            status: 'failed',
+            result: { content: 'partial', durationMs: 9 },
+          },
+        ],
+      },
+    }
+    const overview = parseRunSnapshot(fixture, 'wf-status-runid', '/abs/wf.jsonl')
+    expect(overview).not.toBeNull()
+    expect(overview!.steps).toHaveLength(1)
+    const step = overview!.steps[0]
+    expect(step.index).toBe(3)
+    expect(step.status).toBe('pending')
+    expect(step.description).toBe('step-3')
+    expect(step.contentPreview).toBe('partial')
+    expect(step.durationMs).toBe(9)
+  })
+
   it('TC-w5-parse-old：OLD 格式 (无 v) 尽力解析为 legacy overview，step status 推测', () => {
     const overview = parseRunSnapshot(OLD_SNAPSHOT_FIXTURE, 'wf-old-link', '/abs/wf-old.jsonl')
     expect(overview).not.toBeNull()
@@ -199,6 +226,37 @@ describe('extractCallSessionFiles', () => {
     const files = extractCallSessionFiles(NEW_SNAPSHOT_FIXTURE)
     expect(files).toEqual(['/abs/session.jsonl'])
   })
+
+  it('OLD 快照（无 v，callCache）从 value 顶层与 value.result 提取 sessionFile', () => {
+    const files = extractCallSessionFiles({
+      callCache: [
+        { key: 0, value: { sessionFile: '/abs/old-call0.jsonl' } },
+        { key: 1, value: { result: { sessionFile: '/abs/old-call1.jsonl' } } },
+      ],
+    })
+    expect(files).toEqual(['/abs/old-call0.jsonl', '/abs/old-call1.jsonl'])
+  })
+
+  it('OLD 快照 value 无 sessionFile / value 非对象 → 跳过该 call，不产出路径', () => {
+    // 对齐 OLD_SNAPSHOT_FIXTURE 形状（旧 pi 不持久化 sessionFile）+ value 非对象脏数据回退 call 本身
+    const files = extractCallSessionFiles({
+      callCache: [
+        { key: 7, value: { content: '', usage: { input: 0 } } },
+        { key: 8, value: 42 },
+        { key: 9, sessionFile: '/abs/bare-call.jsonl' },
+      ],
+    })
+    expect(files).toEqual(['/abs/bare-call.jsonl'])
+  })
+
+  it('快照非对象 / calls 容器缺失 / call 元素非对象 → 空数组', () => {
+    expect(extractCallSessionFiles(null)).toEqual([])
+    expect(extractCallSessionFiles('wf-run-v1')).toEqual([])
+    expect(extractCallSessionFiles({ v: 'wf-run-v1', state: null })).toEqual([])
+    expect(extractCallSessionFiles({ v: 'wf-run-v1', state: {} })).toEqual([])
+    expect(extractCallSessionFiles({ callCache: 'not-an-array' })).toEqual([])
+    expect(extractCallSessionFiles({ callCache: [null, 7, 'x'] })).toEqual([])
+  })
 })
 
 // ============================================================
@@ -282,7 +340,7 @@ describe('renderWorkflowOverview', () => {
 describe('readRunSnapshot', () => {
   let dir: string
   afterEach(async () => {
-    if (dir) await rm(dir, { recursive: true, force: true }).catch(() => {})
+    if (dir) await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 }).catch(() => {})
   })
 
   it('TC-w5-read-tail-fallback：末行半截 JSON 回退倒数第二行完整快照', async () => {

package/src/core/family.ts

@@ -134,24 +134,12 @@ function resolveParentSessionId(
   return null
 }
 
-/**
- * 从已读入的 session headers + subagent identity entries 建家族索引（纯逻辑，无 IO）。
- *
- * - headers（type=session）→ byId + childrenOf（parentSession 文件路径反查父 sessionId）
- * - subagentIdentities（type=custom, customType=subagent-identity）→ subagentsByRoot
- * - fileStats 原样存入 index，供 cleanedUp 判断
- *
- * 坏数据容错：identity 缺 rootSessionId/slug 跳过；parentSession 反查不到父（父文件
- * 未被扫描到）该 entry 不进 childrenOf——均不报错，符合 pi 坏 session 容错（design §2）。
- */
-export function buildFamilyIndex(
+/** 阶段 1：headers → byId（SessionRef 组装，mtime/size 从 fileStats 取，取不到为 0）。 */
+function buildById(
   headers: Entry[],
-  subagentIdentities: Entry[],
   fileStats: Map<string, { mtime: number; size: number }>,
-): FamilyIndex {
+): Map<string, SessionRef> {
   const byId = new Map<string, SessionRef>()
-
-  // 1. headers → byId
   for (const h of headers) {
     const stat = fileStats.get(h.id)
     const ref: SessionRef = {
@@ -164,8 +152,17 @@ export function buildFamilyIndex(
     if (h.parentSession) ref.parentSession = h.parentSession
     byId.set(h.id, ref)
   }
+  return byId
+}
 
-  // 2. childrenOf：parentSession（文件路径）→ 反查父 sessionId → key 用父 sessionId
+/**
+ * 阶段 2：childrenOf——parentSession（文件路径）→ 反查父 sessionId → key 用父 sessionId。
+ * 反查不到父 → 无法建反查关系，跳过（不报错，design §2 容错）。
+ */
+function buildChildrenOf(
+  headers: Entry[],
+  byId: Map<string, SessionRef>,
+): Map<string, SessionRef[]> {
   const childrenOf = new Map<string, SessionRef[]>()
   for (const h of headers) {
     if (!h.parentSession) continue
@@ -177,8 +174,17 @@ export function buildFamilyIndex(
     list.push(childRef)
     childrenOf.set(parentSid, list)
   }
+  return childrenOf
+}
 
-  // 3. subagentIdentities → subagentsByRoot
+/**
+ * 阶段 3：subagentIdentities → subagentsByRoot。
+ * 坏数据（缺 rootSessionId/slug）跳过，不报错（design §2 容错）。
+ */
+function buildSubagentsByRoot(
+  subagentIdentities: Entry[],
+  fileStats: Map<string, { mtime: number; size: number }>,
+): Map<string, SubagentRef[]> {
   const subagentsByRoot = new Map<string, SubagentRef[]>()
   for (const ident of subagentIdentities) {
     if (!isSubagentIdentityData(ident.data)) continue // 坏数据（缺 rootSessionId/slug）跳过
@@ -207,7 +213,27 @@ export function buildFamilyIndex(
     list.push(ref)
     subagentsByRoot.set(ident.data.rootSessionId, list)
   }
+  return subagentsByRoot
+}
 
+/**
+ * 从已读入的 session headers + subagent identity entries 建家族索引（纯逻辑，无 IO）。
+ *
+ * - headers（type=session）→ byId + childrenOf（parentSession 文件路径反查父 sessionId）
+ * - subagentIdentities（type=custom, customType=subagent-identity）→ subagentsByRoot
+ * - fileStats 原样存入 index，供 cleanedUp 判断
+ *
+ * 坏数据容错：identity 缺 rootSessionId/slug 跳过；parentSession 反查不到父（父文件
+ * 未被扫描到）该 entry 不进 childrenOf——均不报错，符合 pi 坏 session 容错（design §2）。
+ */
+export function buildFamilyIndex(
+  headers: Entry[],
+  subagentIdentities: Entry[],
+  fileStats: Map<string, { mtime: number; size: number }>,
+): FamilyIndex {
+  const byId = buildById(headers, fileStats)
+  const childrenOf = buildChildrenOf(headers, byId)
+  const subagentsByRoot = buildSubagentsByRoot(subagentIdentities, fileStats)
   return { byId, childrenOf, subagentsByRoot, fileStats }
 }
 

package/src/core/parser.ts

@@ -51,6 +51,31 @@ function isMessageRole(v: unknown): v is 'user' | 'assistant' | 'toolResult' {
   return v === 'user' || v === 'assistant' || v === 'toolResult'
 }
 
+/**
+ * 归一化 message 字段（阶段 helper：role 经值守卫收窄，缺/非法 role 时
+ * 返回 undefined，调用方丢弃 message 字段——接口 role 必填）。
+ */
+function parseEntryMessage(raw: unknown): Entry['message'] | undefined {
+  if (raw === null || typeof raw !== 'object') return undefined
+  const m = raw as Record<string, unknown>
+  if (!isMessageRole(m.role)) return undefined
+  const message: NonNullable<Entry['message']> = { role: m.role, content: m.content }
+  if (Array.isArray(m.toolCalls)) message.toolCalls = m.toolCalls
+  // toolResult 自带的工具关联字段（O2/O3 用，additive，实测 515/515 存在）
+  if (typeof m.toolName === 'string') message.toolName = m.toolName
+  if (typeof m.toolCallId === 'string') message.toolCallId = m.toolCallId
+  return message
+}
+
+/** 归一化剩余可选字段（阶段 helper：customType/data/parentSession/cwd/summary）。 */
+function assignOptionalFields(obj: Record<string, unknown>, entry: Entry): void {
+  if (typeof obj.customType === 'string') entry.customType = obj.customType
+  if (obj.data !== undefined) entry.data = obj.data
+  if (typeof obj.parentSession === 'string') entry.parentSession = obj.parentSession
+  if (typeof obj.cwd === 'string') entry.cwd = obj.cwd
+  if (obj.summary !== undefined) entry.summary = obj.summary
+}
+
 /**
  * 把单个已 JSON.parse 成功的原始对象归一化为 Entry。
  * 缺必填结构字段（type/id）返回 undefined，调用方计为坏行（skippedLines++）。
@@ -74,24 +99,10 @@ function toEntry(raw: unknown): Entry | undefined {
   }
   if (typeof obj.timestamp === 'string') entry.timestamp = obj.timestamp
 
-  // message：role 经值守卫收窄，缺/非法 role 时丢弃 message 字段（接口 role 必填）
-  if (obj.message !== null && typeof obj.message === 'object') {
-    const m = obj.message as Record<string, unknown>
-    if (isMessageRole(m.role)) {
-      const message: NonNullable<Entry['message']> = { role: m.role, content: m.content }
-      if (Array.isArray(m.toolCalls)) message.toolCalls = m.toolCalls
-      // toolResult 自带的工具关联字段（O2/O3 用，additive，实测 515/515 存在）
-      if (typeof m.toolName === 'string') message.toolName = m.toolName
-      if (typeof m.toolCallId === 'string') message.toolCallId = m.toolCallId
-      entry.message = message
-    }
-  }
+  const message = parseEntryMessage(obj.message)
+  if (message !== undefined) entry.message = message
 
-  if (typeof obj.customType === 'string') entry.customType = obj.customType
-  if (obj.data !== undefined) entry.data = obj.data
-  if (typeof obj.parentSession === 'string') entry.parentSession = obj.parentSession
-  if (typeof obj.cwd === 'string') entry.cwd = obj.cwd
-  if (obj.summary !== undefined) entry.summary = obj.summary
+  assignOptionalFields(obj, entry)
 
   return entry
 }

package/src/core/render.ts

@@ -330,6 +330,61 @@ function leafParsedBytes(turns: Turn[]): number {
   return parsedBytes
 }
 
+/** allBranches：对每个 brief 标注所在 turn 的 forkPoint（找到才标 branch）。 */
+function applyBranchLabels(briefs: TurnBrief[], turns: Turn[], tree: TreeView): void {
+  for (const b of briefs) {
+    const fp = findBranchForkPoint(turns[b.index], tree)
+    if (fp !== undefined) b.branch = fp
+  }
+}
+
+/**
+ * 降级序逐行渲染（design §3.5 算法 1 step3）：level 0 全有；超预算降到 level 1
+ * 砍 assistantBrief；仍超降到 level 2 砍 toolSummary（骨架）。
+ * 直接改写 brief 的 assistantBrief/toolSummary 字段，返回行缓存。
+ */
+function renderDegradingLines(
+  briefs: TurnBrief[],
+  tree: TreeView,
+  perTurnCharBudget: number,
+): string[] {
+  const lineCache: string[] = []
+  for (const b of briefs) {
+    const branchSize = b.branch !== undefined ? tree.branches.get(b.branch) : undefined
+    let line = formatLine(b, LINE_LEVEL_FULL, branchSize)
+    if (line.length > perTurnCharBudget) {
+      // 超预算：先砍 assistantBrief（level 1），仍超再砍 toolSummary（level 2，骨架）
+      b.assistantBrief = ''
+      line = formatLine(b, LINE_LEVEL_NO_ASSISTANT, branchSize)
+      if (line.length > perTurnCharBudget) {
+        b.toolSummary = ''
+        line = formatLine(b, LINE_LEVEL_SKELETON, branchSize)
+      }
+    }
+    lineCache.push(line)
+  }
+  return lineCache
+}
+
+/** 总预算截断（从尾部丢弃）：就地截短 lines 与 briefs，返回最终 totalChars 与 truncated。 */
+function truncateToTotalBudget(
+  briefs: TurnBrief[],
+  lines: string[],
+  budget: number,
+): { totalChars: number; truncated: number | undefined } {
+  let totalChars = lines.reduce((s, l) => s + l.length, 0)
+  if (totalChars / CHARS_PER_TOKEN <= budget) return { totalChars, truncated: undefined }
+  let kept = lines.length
+  while (kept > 0 && totalChars / CHARS_PER_TOKEN > budget) {
+    kept--
+    totalChars -= lines[kept].length
+  }
+  const truncated = lines.length - kept
+  lines.length = kept
+  briefs.length = kept
+  return { totalChars, truncated }
+}
+
 export function renderOutline(
   turns: Turn[],
   tree: TreeView,
@@ -365,46 +420,16 @@ export function renderOutline(
   const briefs: TurnBrief[] = turns.map(computeBrief)
 
   // allBranches：标注 forkPoint
-  if (allBranches) {
-    for (const b of briefs) {
-      const fp = findBranchForkPoint(turns[b.index], tree)
-      if (fp !== undefined) b.branch = fp
-    }
-  }
+  if (allBranches) applyBranchLabels(briefs, turns, tree)
 
   // 2. perTurnBudget（token → chars×4）
   const perTurnCharBudget = (budget / turns.length) * CHARS_PER_TOKEN
 
-  // 3. 降级序：level 0 全有；超预算降到 level 1 砍 assistantBrief；仍超降到 level 2 砍 toolSummary（骨架）。design §3.5 算法 1 step3
-  const lineCache: string[] = []
-  for (const b of briefs) {
-    const branchSize = b.branch !== undefined ? tree.branches.get(b.branch) : undefined
-    let line = formatLine(b, LINE_LEVEL_FULL, branchSize)
-    if (line.length > perTurnCharBudget) {
-      // 超预算：先砍 assistantBrief（level 1），仍超再砍 toolSummary（level 2，骨架）
-      b.assistantBrief = ''
-      line = formatLine(b, LINE_LEVEL_NO_ASSISTANT, branchSize)
-      if (line.length > perTurnCharBudget) {
-        b.toolSummary = ''
-        line = formatLine(b, LINE_LEVEL_SKELETON, branchSize)
-      }
-    }
-    lineCache.push(line)
-  }
+  // 3. 降级序渲染：level 0 全有 → level 1 砍 assistantBrief → level 2 骨架
+  const lineCache = renderDegradingLines(briefs, tree, perTurnCharBudget)
 
   // 4. 总预算截断（从尾部丢弃）
-  let totalChars = lineCache.reduce((s, l) => s + l.length, 0)
-  let truncated: number | undefined
-  if (totalChars / CHARS_PER_TOKEN > budget) {
-    let kept = lineCache.length
-    while (kept > 0 && totalChars / CHARS_PER_TOKEN > budget) {
-      kept--
-      totalChars -= lineCache[kept].length
-    }
-    truncated = lineCache.length - kept
-    lineCache.length = kept
-    briefs.length = kept
-  }
+  const { totalChars, truncated } = truncateToTotalBudget(briefs, lineCache, budget)
 
   const tokenEstimate = Math.ceil(totalChars / CHARS_PER_TOKEN)
   return { turns: briefs, stats, tokenEstimate, truncated }

package/src/core/toolcall.ts

@@ -102,11 +102,111 @@ function numArg(args: Record<string, unknown>, k: string): number | undefined {
   return typeof v === 'number' ? v : undefined
 }
 
+// ---------------------------------------------------------------------------
+// 各工具参数摘要 formatter（design §3.3 D1 表的表驱动形态，每个 case 体一个函数）
+// ---------------------------------------------------------------------------
+
+/** 单工具参数摘要 formatter：输入归一化后的 arguments，输出摘要串（参数缺失时优雅降级）。 */
+type ArgsFormatter = (args: Record<string, unknown>) => string
+
+function formatBashArgs(args: Record<string, unknown>): string {
+  const cmd = strArg(args, 'command')
+  return cmd !== undefined ? `bash: ${truncate(cmd, BASH_CMD_MAX_CHARS)}` : 'bash'
+}
+
+function formatReadArgs(args: Record<string, unknown>): string {
+  const p = strArg(args, 'path')
+  return p !== undefined ? `read: ${basename(p)}` : 'read'
+}
+
+function formatEditArgs(args: Record<string, unknown>): string {
+  const p = strArg(args, 'path')
+  const edits = args.edits
+  const blocks = Array.isArray(edits) ? edits.length : undefined
+  const head = p !== undefined ? `edit: ${basename(p)}` : 'edit'
+  return blocks !== undefined ? `${head} (${blocks} blocks)` : head
+}
+
+function formatWriteArgs(args: Record<string, unknown>): string {
+  const p = strArg(args, 'path')
+  const c = strArg(args, 'content')
+  const head = p !== undefined ? `write: ${basename(p)}` : 'write'
+  if (c === undefined) return head
+  // utf8 字节转 KB 取整；小文件至少 1KB（0KB 无信息量）
+  const kb = Math.max(1, Math.round(Buffer.byteLength(c, 'utf8') / BYTES_PER_KB))
+  return `${head} (${kb}KB)`
+}
+
+function formatSubagentArgs(args: Record<string, unknown>): string {
+  const task = strArg(args, 'task')
+  return task !== undefined ? `subagent: ${truncate(task, SUBAGENT_TASK_MAX_CHARS)}` : 'subagent'
+}
+
+function formatHeadArgs(args: Record<string, unknown>): string {
+  const p = strArg(args, 'path')
+  // limit 可能是 number 或 string（实测 number，防御 string）
+  const lim: number | string | undefined = numArg(args, 'limit') ?? strArg(args, 'limit')
+  const head = p !== undefined ? `head: ${basename(p)}` : 'head'
+  return lim !== undefined ? `${head} (${lim})` : head
+}
+
+function formatTodoArgs(args: Record<string, unknown>): string {
+  const action = strArg(args, 'action')
+  if (action === undefined) return 'todo'
+  // id 可能是 number（todo 列表 id）或 string
+  const id = args.id
+  const idStr =
+    typeof id === 'string' ? id : typeof id === 'number' ? String(id) : undefined
+  return idStr !== undefined ? `todo: ${action}(${idStr})` : `todo: ${action}`
+}
+
+function formatCwGateArgs(args: Record<string, unknown>): string {
+  const phase = args.phase
+  return phase !== undefined ? `cw-gate: phase=${String(phase)}` : 'cw-gate'
+}
+
+function formatCwInitArgs(args: Record<string, unknown>): string {
+  const slug = strArg(args, 'slug')
+  return slug !== undefined ? `cw-init: ${slug}` : 'cw-init'
+}
+
 /**
- * 按工具类型把 ToolCallInfo 映射成参数摘要串（design §3.3 D1 表）。
+ * 未知工具 fallback（原 switch default）：arguments 非空 → name: <json 前50>；
+ * 空对象 → 仅 name（{} 无信息量）。
+ */
+function formatUnknownTool(name: string, args: Record<string, unknown>): string {
+  if (Object.keys(args).length === 0) return name
+  try {
+    return `${name}: ${truncate(JSON.stringify(args), ARGS_JSON_MAX_CHARS)}`
+  } catch {
+    return name
+  }
+}
+
+/**
+ * 工具名 → 参数摘要 formatter 表（design §3.3 D1 表；phase-start 无参数维度恒返常量）。
+ * 用 Map 而非普通对象：name 是外部输入（pi session JSONL 的 toolName），普通对象查表会
+ * 命中 Object.prototype 上的键（如 "constructor"），导致把非函数当 formatter 调用；Map 只查自身键。
+ */
+const TOOL_SUMMARY_FORMATTERS: ReadonlyMap<string, ArgsFormatter> = new Map([
+  ['bash', formatBashArgs],
+  ['read', formatReadArgs],
+  ['edit', formatEditArgs],
+  ['write', formatWriteArgs],
+  ['subagent', formatSubagentArgs],
+  ['head', formatHeadArgs],
+  ['todo', formatTodoArgs],
+  ['coding-workflow-gate', formatCwGateArgs],
+  ['coding-workflow-init', formatCwInitArgs],
+  ['coding-workflow-phase-start', () => 'cw-phase-start'],
+])
+
+/**
+ * 按工具类型把 ToolCallInfo 映射成参数摘要串（design §3.3 D1 表，表驱动分发）。
  *
- * 参数缺失时优雅降级（只输出工具名或省略对应维度）。未知工具 fallback 带 arguments JSON
- * 前 50 字；arguments 为空对象时省略 JSON（`{}` 无信息量）。
+ * 参数缺失时优雅降级（只输出工具名或省略对应维度）。未知工具（表落空）走
+ * formatUnknownTool：带 arguments JSON 前 50 字；arguments 为空对象时省略 JSON
+ * （`{}` 无信息量）。
  *
  * 单位口径：edit 的 blocks 是参数维度（edits 数组长度），write 的 KB 是参数维度（content 字节），
  * 这两者已含参数规模；O2/O3 的 toolResult 摘要在此基础再加结果规模时，bash/read 单独 append
@@ -114,70 +214,6 @@ function numArg(args: Record<string, unknown>, k: string): number | undefined {
  */
 export function formatToolCallSummary(tc: ToolCallInfo): string {
   const { name, arguments: args } = tc
-
-  switch (name) {
-    case 'bash': {
-      const cmd = strArg(args, 'command')
-      return cmd !== undefined ? `bash: ${truncate(cmd, BASH_CMD_MAX_CHARS)}` : 'bash'
-    }
-    case 'read': {
-      const p = strArg(args, 'path')
-      return p !== undefined ? `read: ${basename(p)}` : 'read'
-    }
-    case 'edit': {
-      const p = strArg(args, 'path')
-      const edits = args.edits
-      const blocks = Array.isArray(edits) ? edits.length : undefined
-      const head = p !== undefined ? `edit: ${basename(p)}` : 'edit'
-      return blocks !== undefined ? `${head} (${blocks} blocks)` : head
-    }
-    case 'write': {
-      const p = strArg(args, 'path')
-      const c = strArg(args, 'content')
-      const head = p !== undefined ? `write: ${basename(p)}` : 'write'
-      if (c === undefined) return head
-      // utf8 字节转 KB 取整；小文件至少 1KB（0KB 无信息量）
-      const kb = Math.max(1, Math.round(Buffer.byteLength(c, 'utf8') / BYTES_PER_KB))
-      return `${head} (${kb}KB)`
-    }
-    case 'subagent': {
-      const task = strArg(args, 'task')
-      return task !== undefined ? `subagent: ${truncate(task, SUBAGENT_TASK_MAX_CHARS)}` : 'subagent'
-    }
-    case 'head': {
-      const p = strArg(args, 'path')
-      // limit 可能是 number 或 string（实测 number，防御 string）
-      const lim: number | string | undefined = numArg(args, 'limit') ?? strArg(args, 'limit')
-      const head = p !== undefined ? `head: ${basename(p)}` : 'head'
-      return lim !== undefined ? `${head} (${lim})` : head
-    }
-    case 'todo': {
-      const action = strArg(args, 'action')
-      if (action === undefined) return 'todo'
-      // id 可能是 number（todo 列表 id）或 string
-      const id = args.id
-      const idStr =
-        typeof id === 'string' ? id : typeof id === 'number' ? String(id) : undefined
-      return idStr !== undefined ? `todo: ${action}(${idStr})` : `todo: ${action}`
-    }
-    case 'coding-workflow-gate': {
-      const phase = args.phase
-      return phase !== undefined ? `cw-gate: phase=${String(phase)}` : 'cw-gate'
-    }
-    case 'coding-workflow-init': {
-      const slug = strArg(args, 'slug')
-      return slug !== undefined ? `cw-init: ${slug}` : 'cw-init'
-    }
-    case 'coding-workflow-phase-start':
-      return 'cw-phase-start'
-    default: {
-      // 未知工具：arguments 非空 → name: <json 前50>；空对象 → 仅 name（{} 无信息量）
-      if (Object.keys(args).length === 0) return name
-      try {
-        return `${name}: ${truncate(JSON.stringify(args), ARGS_JSON_MAX_CHARS)}`
-      } catch {
-        return name
-      }
-    }
-  }
+  const formatter = TOOL_SUMMARY_FORMATTERS.get(name)
+  return formatter !== undefined ? formatter(args) : formatUnknownTool(name, args)
 }