@zhushanwen/pi-session-reader 0.3.1 → 0.4.0

package/src/__tests__/result.test.ts

@@ -0,0 +1,341 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  handleSessionRead,
+  extractFinalAssistantText,
+  type SessionReadParams,
+} from '../tool-handler.js'
+
+/**
+ * U6 result action 测试（design subagent-sync-collect §3.1.3 + impl-plan U6）。
+ *
+ * 覆盖（任务验收用例清单）：
+ * 1. 单 id 取回正文与预期一致（sa-id manifest 反查，同源语义：无包装纯正文）
+ * 2. 批量 ≤10（3 id，头行 + 分隔 + 顺序保持）
+ * 3. 批量 >10 拒绝（文案含上限 10）
+ * 4. limit 截断 + 尾提示（默认 8000 + 显式 limit）
+ * 5. 不存在 id 报错（sa-id / uuid 片段两路）
+ * 6. 空 assistant 报错（文件无 assistant 消息）
+ * 7. 文件尚未 flush 报错（manifest 有、sessionFile 不存在——pi 延迟写入）
+ *
+ * 红线：vitest；fixture 全部 mkdtemp(tmpdir) 自建自删，零真实数据目录触碰。
+ * extractFinalAssistantText 纯函数白盒：同源重建规则锁定（与 record.result 逐字节
+ * 一致的前置，A4 取回门）。
+ */
+
+// ---- fixture 工具（合成 subagent session，同 tool-handler.test.ts makeFixtureSubagent 结构）----
+
+const SLUG = '--demo-cwd--'
+
+interface SubagentFixture {
+  saId: string
+  realId: string
+  /** header + user 任务之后追加的 entries（assistant 消息等） */
+  entries?: unknown[]
+  /** false = 只写 manifest 不写 session 文件（模拟 pi 延迟写入未 flush / GC） */
+  sessionFileExists?: boolean
+}
+
+function assistantEntry(id: string, content: unknown): unknown {
+  return {
+    type: 'message',
+    id,
+    parentId: 'p',
+    message: { role: 'assistant', content },
+  }
+}
+
+async function makeSubagent(dir: string, f: SubagentFixture): Promise<string> {
+  const sessionFile = join(dir, 'subagents', SLUG, 'sessions', `${f.realId}.jsonl`)
+  if (f.sessionFileExists !== false) {
+    await mkdir(join(dir, 'subagents', SLUG, 'sessions'), { recursive: true })
+    const header = JSON.stringify({ type: 'session', id: f.realId, cwd: '/demo' })
+    const task = JSON.stringify({
+      type: 'message',
+      id: `${f.realId}-u1`,
+      parentId: f.realId,
+      message: { role: 'user', content: [{ type: 'text', text: 'do the task' }] },
+    })
+    const lines = [header, task, ...(f.entries ?? []).map((e) => JSON.stringify(e))]
+    await writeFile(sessionFile, lines.join('\n') + '\n')
+  }
+  const recordsDir = join(dir, 'subagents', SLUG, 'records')
+  await mkdir(recordsDir, { recursive: true })
+  await writeFile(
+    join(recordsDir, `${f.saId}.json`),
+    JSON.stringify({
+      id: f.saId,
+      rootSessionId: 'root-session-1',
+      agentName: 'explorer',
+      sessionFile,
+    }),
+  )
+  return sessionFile
+}
+
+// ---- extractFinalAssistantText 纯函数白盒（同源重建规则） ----
+
+describe('extractFinalAssistantText（同源语义白盒）', () => {
+  it('message 内多 text 块无分隔拼接（text_delta 直累积同构）；thinking/toolCall 排除', () => {
+    const text = extractFinalAssistantText([
+      assistantEntry('a1', [
+        { type: 'thinking', thinking: 'should not appear' },
+        { type: 'text', text: 'AB' },
+        { type: 'text', text: 'CD' },
+        { type: 'toolCall', toolCallId: 'tc1', name: 'bash' },
+      ]),
+    ])
+    expect(text).toBe('ABCD')
+  })
+
+  it('跨 assistant message 非空过滤 join("\\n\\n")（getFullText 同构）；字符串 content 直取', () => {
+    const text = extractFinalAssistantText([
+      assistantEntry('a1', [{ type: 'text', text: 'first' }]),
+      assistantEntry('a2', []), // 空 content → 过滤
+      assistantEntry('a3', 'plain string content'), // 字符串形态
+    ])
+    expect(text).toBe('first\n\nplain string content')
+  })
+
+  it('只取最后一条 user message 之后的 assistant 文本（多轮 session 对齐最终一轮）', () => {
+    const text = extractFinalAssistantText([
+      assistantEntry('r1', [{ type: 'text', text: 'round one' }]),
+      { type: 'message', id: 'u2', parentId: 'x', message: { role: 'user', content: [{ type: 'text', text: 'next round' }] } },
+      assistantEntry('r2', [{ type: 'text', text: 'round two' }]),
+    ])
+    expect(text).toBe('round two')
+  })
+
+  it('无 user message 时计入全部 assistant（防御形态）', () => {
+    const text = extractFinalAssistantText([
+      assistantEntry('a1', [{ type: 'text', text: 'solo' }]),
+    ])
+    expect(text).toBe('solo')
+  })
+
+  it('空 entries → 空串（空 assistant 报错路径的判定基础）', () => {
+    expect(extractFinalAssistantText([])).toBe('')
+  })
+})
+
+// ---- result action 黑盒（fixture：sa-id manifest 反查主路径） ----
+
+describe('result action（U6）', () => {
+  let dir: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'session-reader-result-'))
+  })
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  it('1. 单 id：返回纯正文（无包装），details 带元数据（sessionId=header 真实 id）', async () => {
+    const realId = '019e6c96-dddd-eeee-ffff-000000000001'
+    await makeSubagent(dir, {
+      saId: 'sa-one',
+      realId,
+      entries: [
+        assistantEntry(`${realId}-a1`, [
+          { type: 'thinking', thinking: 'quiet thinking' },
+          { type: 'text', text: 'FINAL RESULT' },
+          { type: 'toolCall', toolCallId: 'tc1', name: 'read' },
+        ]),
+        {
+          type: 'message',
+          id: `${realId}-t1`,
+          parentId: `${realId}-a1`,
+          message: { role: 'toolResult', content: [{ type: 'text', text: 'file body' }], toolName: 'read', toolCallId: 'tc1' },
+        },
+        assistantEntry(`${realId}-a2`, [{ type: 'text', text: 'second part' }]),
+      ],
+    })
+    const r = await handleSessionRead({ action: 'result', session: 'sa-one' }, dir)
+    // 与 record.result 同源：全部 assistant 正文非空过滤 '\n\n' join，无任何包装
+    expect(r.content[0]?.text).toBe('FINAL RESULT\n\nsecond part')
+    const d = r.details as {
+      session: string
+      sessionId: string
+      sessionFile: string
+      totalChars: number
+      truncated: boolean
+    }
+    expect(d.session).toBe('sa-one')
+    expect(d.sessionId).toBe(realId) // header 真实 id，非 sa- 占位
+    expect(d.sessionFile).toContain(realId)
+    expect(d.totalChars).toBe('FINAL RESULT\n\nsecond part'.length)
+    expect(d.truncated).toBe(false)
+  })
+
+  it('2. 批量 ≤10：3 id 各带头行与正文，"---" 分隔，顺序与输入一致', async () => {
+    const ids = [
+      { saId: 'sa-b1', realId: '019e6c96-0000-0000-0000-000000000b01', text: 'alpha result' },
+      { saId: 'sa-b2', realId: '019e6c96-0000-0000-0000-000000000b02', text: 'beta result' },
+      { saId: 'sa-b3', realId: '019e6c96-0000-0000-0000-000000000b03', text: 'gamma result' },
+    ]
+    for (const f of ids) {
+      await makeSubagent(dir, {
+        saId: f.saId,
+        realId: f.realId,
+        entries: [assistantEntry(`${f.realId}-a1`, [{ type: 'text', text: f.text }])],
+      })
+    }
+    const r = await handleSessionRead(
+      { action: 'result', session: 'sa-b1,sa-b2,sa-b3' },
+      dir,
+    )
+    const text = r.content[0]?.text ?? ''
+    expect(text).toContain('[1/3] sa-b1')
+    expect(text).toContain('[2/3] sa-b2')
+    expect(text).toContain('[3/3] sa-b3')
+    expect(text).toContain('alpha result')
+    expect(text).toContain('beta result')
+    expect(text).toContain('gamma result')
+    // 顺序保持：alpha 头行位于 beta 头行之前
+    expect(text.indexOf('[1/3]')).toBeLessThan(text.indexOf('[2/3]'))
+    expect(text.indexOf('[2/3]')).toBeLessThan(text.indexOf('[3/3]'))
+    // 条目分隔（与批通知同款）
+    expect(text).toContain('\n\n---\n\n')
+    const d = r.details as { count: number; items: Array<{ session: string; truncated: boolean }> }
+    expect(d.count).toBe(3)
+    expect(d.items.map((i) => i.session)).toEqual(['sa-b1', 'sa-b2', 'sa-b3'])
+    expect(d.items.every((i) => !i.truncated)).toBe(true)
+  })
+
+  it('3. 批量 >10：11 id 拒绝，报错含上限 10 与分批指引（解析先于 fs，无需 fixture）', async () => {
+    const list = Array.from({ length: 11 }, (_, i) => `sa-x${i}`).join(',')
+    await expect(
+      handleSessionRead({ action: 'result', session: list }, dir),
+    ).rejects.toThrow(/最多 10 个/)
+    try {
+      await handleSessionRead({ action: 'result', session: list }, dir)
+    } catch (e) {
+      const msg = (e as Error).message
+      expect(msg).toContain('11')
+      expect(msg).toContain('👉')
+    }
+  })
+
+  it('4. limit 默认 8000：8001 字符正文截断到 8000 + 尾提示（读原文件指引）', async () => {
+    const realId = '019e6c96-0000-0000-0000-000000000c01'
+    const longText = 'x'.repeat(8001)
+    const sessionFile = await makeSubagent(dir, {
+      saId: 'sa-long',
+      realId,
+      entries: [assistantEntry(`${realId}-a1`, [{ type: 'text', text: longText }])],
+    })
+    const r = await handleSessionRead({ action: 'result', session: 'sa-long' }, dir)
+    const text = r.content[0]?.text ?? ''
+    // 截断到 8000：第 8001 个 x 不在正文，但提示行给出计数
+    expect(text.startsWith('x'.repeat(8000))).toBe(true)
+    expect(text).not.toBe(longText)
+    expect(text).toContain('[truncated 8000 of 8001 chars')
+    expect(text).toContain(`read ${sessionFile}`)
+    expect(text).toContain('session_read { action:"detail", session:"sa-long" }')
+    const d = r.details as { totalChars: number; truncated: boolean; sessionFile: string }
+    expect(d.totalChars).toBe(8001)
+    expect(d.truncated).toBe(true)
+    expect(d.sessionFile).toBe(sessionFile)
+  })
+
+  it('5. 显式 limit：5 字符截断 + 提示；limit 恰等长度不截断；非法 limit 报错', async () => {
+    const realId = '019e6c96-0000-0000-0000-000000000c02'
+    await makeSubagent(dir, {
+      saId: 'sa-lim',
+      realId,
+      entries: [assistantEntry(`${realId}-a1`, [{ type: 'text', text: 'abcdefghij' }])],
+    })
+    const cut = await handleSessionRead(
+      { action: 'result', session: 'sa-lim', limit: 5 },
+      dir,
+    )
+    expect(cut.content[0]?.text).toBe(
+      'abcde\n\n[truncated 5 of 10 chars — full text: read ' +
+        `${join(dir, 'subagents', SLUG, 'sessions', `${realId}.jsonl`)}` +
+        ', or session_read { action:"detail", session:"sa-lim" }]',
+    )
+    const exact = await handleSessionRead(
+      { action: 'result', session: 'sa-lim', limit: 10 },
+      dir,
+    )
+    expect(exact.content[0]?.text).toBe('abcdefghij')
+    const d = exact.details as { truncated: boolean }
+    expect(d.truncated).toBe(false)
+    for (const bad of [0, -1, Number.NaN]) {
+      await expect(
+        handleSessionRead({ action: 'result', session: 'sa-lim', limit: bad }, dir),
+      ).rejects.toThrow(/limit.*无效/)
+    }
+  })
+
+  it('6. 不存在 id：sa-id 无 manifest → 无匹配 record；uuid 片段零匹配 → 无匹配 session', async () => {
+    await expect(
+      handleSessionRead({ action: 'result', session: 'sa-nonexist-9999' }, dir),
+    ).rejects.toThrow(/无匹配 record/)
+    try {
+      await handleSessionRead({ action: 'result', session: 'sa-nonexist-9999' }, dir)
+    } catch (e) {
+      const msg = (e as Error).message
+      expect(msg).toContain('👉')
+      expect(msg).toContain('family')
+    }
+    await expect(
+      handleSessionRead({ action: 'result', session: 'zzz-nonexistent-9q8x2' }, dir),
+    ).rejects.toThrow(/无匹配 session/)
+  })
+
+  it('7. 文件尚未 flush：manifest 有、sessionFile 不存在 → 明确报错（GC/未写入）', async () => {
+    await makeSubagent(dir, {
+      saId: 'sa-flush',
+      realId: '019e6c96-0000-0000-0000-000000000e01',
+      sessionFileExists: false,
+    })
+    await expect(
+      handleSessionRead({ action: 'result', session: 'sa-flush' }, dir),
+    ).rejects.toThrow(/session 文件不存在/)
+    try {
+      await handleSessionRead({ action: 'result', session: 'sa-flush' }, dir)
+    } catch (e) {
+      const msg = (e as Error).message
+      expect(msg).toContain('未写入')
+      expect(msg).toContain('👉')
+    }
+  })
+
+  it('8. 空 assistant：文件只有 header + user 任务 → 尚无 assistant 输出报错', async () => {
+    await makeSubagent(dir, {
+      saId: 'sa-empty',
+      realId: '019e6c96-0000-0000-0000-000000000a01',
+    })
+    await expect(
+      handleSessionRead({ action: 'result', session: 'sa-empty' }, dir),
+    ).rejects.toThrow(/尚无 assistant 输出/)
+    try {
+      await handleSessionRead({ action: 'result', session: 'sa-empty' }, dir)
+    } catch (e) {
+      const msg = (e as Error).message
+      expect(msg).toContain('sa-empty')
+      expect(msg).toContain('👉')
+    }
+  })
+
+  it('9. 参数防御：缺 session / 空条目（尾逗号）均报错', async () => {
+    await expect(
+      handleSessionRead({ action: 'result' } as SessionReadParams, dir),
+    ).rejects.toThrow(/需要参数 "session"/)
+    await expect(
+      handleSessionRead({ action: 'result', session: 'sa-a,' }, dir),
+    ).rejects.toThrow(/空条目/)
+  })
+
+  it('10. 未知 action 报错文案含 result（10 action 全列举）', async () => {
+    await expect(
+      handleSessionRead(
+        { action: 'bogus' } as unknown as SessionReadParams,
+        dir,
+      ),
+    ).rejects.toThrow(/find\/family\/outline\/expand\/detail\/search\/export\/extract\/workflow\/result/)
+  })
+})

package/src/__tests__/roots.test.ts

@@ -12,7 +12,7 @@ describe('listMainSessions', () => {
     dir = await mkdtemp(join(tmpdir(), 'roots-test-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('扫描 sessions/<slug>/*.jsonl，排除 *.jsonl.finalized', async () => {
@@ -90,7 +90,7 @@ describe('listSubagentSessions', () => {
     dir = await mkdtemp(join(tmpdir(), 'roots-sub-test-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('扫描 subagents/<slug>/sessions/*.jsonl，排除 .finalized', async () => {

package/src/__tests__/session-command.test.ts

@@ -72,7 +72,7 @@ describe('createSessionCommand - getArgumentCompletions', () => {
     await mkdir(cwdSessionDir, { recursive: true })
   })
   afterEach(async () => {
-    await rm(agentDir, { recursive: true, force: true })
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('空参数 → recent 列表（value=完整 uuid 剥 #，label 含预览）', async () => {
@@ -129,7 +129,7 @@ describe('createSessionCommand - handler select 流程', () => {
     await mkdir(cwdSessionDir, { recursive: true })
   })
   afterEach(async () => {
-    await rm(agentDir, { recursive: true, force: true })
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('选中 label → setEditorText(#完整 uuid + 尾随空格)（value 语义保持完整 uuid）', async () => {

package/src/__tests__/subagents.test.ts

@@ -196,7 +196,7 @@ describe('buildFamilyFromFs - fixture', () => {
     dir = await makeAgentDir()
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('基础 family：root + fork + 隔代 subagent，SubagentRef.sessionId 是真实 id（非 sa-xxx）', async () => {
@@ -514,7 +514,7 @@ describe('listRecordManifests 导出（w2 TC1）', () => {
     dir = await makeAgentDir()
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('导出生效：import + 调用返回 RecordManifest[]，字段完整', async () => {
@@ -545,7 +545,7 @@ describe('U4 buildFamilyFromFs 富化（manifest 主 / P-fallback）', () => {
     dir = await makeAgentDir()
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('TC-u4-manifest-enrich: alive + manifest 全字段 → SubagentRef 富字段全透传', async () => {

package/src/discovery/subagents.ts

@@ -20,7 +20,8 @@ import { resolveWorkflows } from './workflows.js'
  *   M2 用 subagent 文件首行 header.id（真实 session id）替换之，使 SubagentRef.sessionId
  *   是真实 id，Q1 隔代关联仍用 data.rootSessionId（不变）。
  * - cleanedUp：subagent 文件被 30 天 TTL GC 后，identity（在文件尾）一并消失。唯一残留痕迹
- *   是 records/<sa-id>.json manifest（subagent 创建时写入，持久存在）。故 manifest 是孤儿/
+ *   是 records/<sa-id>.json manifest（终态 finalize 或 sync 批落标出口写入——subagent
+ *   创建时不写，两写点均先于 30 天 GC 落盘，故 GC 后必残留）。manifest 是孤儿/
  *   cleanedUp 的来源（design §3.3 D-7 "records/*.json manifest 作孤儿补充"）。
  * - workflows：M1 resolveFamily 恒返回 []。M2 在此单独读目标 session 的 workflow-state-link
  *   custom entry → link.data.path（wf-state 文件绝对路径）→ 从文件尾向头找首个非空且
@@ -195,7 +196,8 @@ async function collectSubagentIdentities(
 
 /**
  * 步骤 3：records manifest → 孤儿（cleanedUp，ES-orphan-manifest）。
- * manifest 在 subagent 创建时写入，.jsonl 被 GC 后仍残留。alive 的（sessionFile 已在步骤 2
+ * manifest 由终态 finalize / sync 批落标出口写入（创建时不写），.jsonl 被 GC 后仍
+ * 残留。alive 的（sessionFile 已在步骤 2
  * 扫到）跳过；未扫到的 = 文件已 GC → 孤儿。用 manifest 完整富字段填 SubagentRef，
  * sessionFile 保留 manifest 的 GC 路径（不置空，供 LLM 知晓原位置），cleanedUp 由
  * buildFamilyIndex 的 !fileStats.has(ident.id) 判 true（ident.id=manifest.id 不在 fileStats）。
@@ -383,7 +385,7 @@ export interface RecordManifest {
   id: string
   rootSessionId: string
   agentName?: string
-  /** subagent session.jsonl 绝对路径（创建时写入；文件 GC 后路径仍残留） */
+  /** subagent session.jsonl 绝对路径（manifest 写入时快照；文件 GC 后路径仍残留） */
   sessionFile: string
   /** subagent 任务文本（探针 20/20 全有；旧 manifest 缺→undefined） */
   task?: string
@@ -425,8 +427,8 @@ async function tryReadManifest(path: string): Promise<RecordManifest | undefined
 
 /**
  * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
- * 每个 manifest 在 subagent 创建时写入，持久存在即使 .jsonl 被 GC。坏 manifest（缺必填字段
- * /JSON 损坏）跳过，不中断扫描。
+ * 每个 manifest 由终态 finalize 或 sync 批落标出口写入（创建时不写），持久存在即使
+ * .jsonl 被 GC。坏 manifest（缺必填字段/JSON 损坏）跳过，不中断扫描。
  */
 export async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
   const root = join(agentDir, 'subagents')

package/src/index.ts

@@ -21,16 +21,27 @@ import { createSessionCommand } from './tui/session-command.js'
 
 const SessionReadSchema = Type.Object({
   action: StringEnum(
-    ['find', 'family', 'outline', 'expand', 'detail', 'search', 'export', 'extract', 'workflow'],
+    [
+      'find',
+      'family',
+      'outline',
+      'expand',
+      'detail',
+      'search',
+      'export',
+      'extract',
+      'workflow',
+      'result',
+    ],
     {
       description:
-        'Action to perform: find (locate session), family (fork/subagent/workflow relations; recursive=true returns nested execution tree), outline (turn-level overview), expand (single-turn entries), detail (full text of turns), search (full-text grep), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps; requires session, optional runId focuses one run; step call sessionId jumps to outline/detail).',
+        'Action to perform: find (locate session), family (fork/subagent/workflow relations; recursive=true returns nested execution tree), outline (turn-level overview), expand (single-turn entries), detail (full text of turns), search (full-text grep), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps; requires session, optional runId focuses one run; step call sessionId jumps to outline/detail), result (fetch a subagent session final result text — same content as its completion notice; session = single id or comma-separated batch of at most 10, optional limit caps chars per item).',
     },
   ),
   session: Type.Optional(
     Type.String({
       description:
-        'Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, precise lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail/search/export/extract/workflow. # prefix auto-stripped.',
+        'Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, precise lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail/search/export/extract/workflow/result. result also accepts a comma-separated list of up to 10 ids. # prefix auto-stripped.',
     }),
   ),
   query: Type.Optional(
@@ -91,7 +102,10 @@ const SessionReadSchema = Type.Object({
     }),
   ),
   limit: Type.Optional(
-    Type.Number({ description: 'find/search: max results. Default 20.' }),
+    Type.Number({
+      description:
+        'find/search: max results. Default 20. result: max chars per item, default 8000 (overlong text truncated with a pointer to the full file).',
+    }),
   ),
   what: Type.Optional(
     StringEnum(
@@ -129,12 +143,13 @@ const guidelines = [
   'family traces fork parents/children, subagent sessions, and workflow runs.',
   'extract what=<type> to pull user messages / commands / files / commits / tool results across turns (optional tool= filter for commands/tool-results).',
   "workflow action to see workflow run overviews (status/budget/steps). Each step's call sessionId can jump to outline/detail for deep reading.",
+  "result action to fetch a subagent's final result text (same content as its completion notice): session takes a single sa-id/uuid/path or a comma-separated batch of at most 10; optional limit caps chars per item (default 8000, truncated items carry a pointer to the full file).",
   'Errors carry a 👉 recovery hint—follow it to retry in one step.',
 ]
 
 // ---- 工具 description（design §3.4，照搬措辞）----
 
-const description = `Read pi session files (conversation history) by semantic structure instead of raw bytes. Use when you need to review another session, trace a fork/subagent/workflow family, or locate a past decision. Nine actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~1500 token), expand (single-turn entry list), detail (full text of turns), search (full-text grep across a session), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps, step call sessionId jumps to outline/detail). Progressive reading: outline → expand → detail. Do NOT use for the current session (the host provides current-session access) or to edit sessions (pi has /resume /fork).`
+const description = `Read pi session files (conversation history) by semantic structure instead of raw bytes. Use when you need to review another session, trace a fork/subagent/workflow family, or locate a past decision. Ten actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~1500 token), expand (single-turn entry list), detail (full text of turns), search (full-text grep across a session), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps, step call sessionId jumps to outline/detail), result (fetch a subagent session final result text, same content as its completion notice; single id or comma-separated batch ≤10, optional limit chars per item default 8000). Progressive reading: outline → expand → detail. Do NOT use for the current session (the host provides current-session access) or to edit sessions (pi has /resume /fork).`
 
 /**
  * 已注册过 TUI provider/command 的 pi 实例集合。