bothouse-dsh 0.1.0 → 0.1.40

package/collab/approvals.mjs

@@ -0,0 +1,177 @@
+// Channel approval cards (#120, #557): one permission card in a room, decided by
+// the owner with a button or a text reply. Member-type neutral: cloud-web bots
+// (cloudweb.mjs) and DSH members (dsh-member.mjs) both open their cards here and
+// get the decision back through their own callback, so the card, the pending
+// table, the text vocabulary and the HTTP route are shared.
+//
+//   const { messageId, decision } = ChannelApprovals.of(hub).open({
+//     room, author: { id, name }, text,
+//     actions: [{ decision: 'allow', label: '允许' }, ...],   // default: DEFAULT_ACTIONS
+//     signal,                       // abort = request withdrawn, card expires
+//     meta,                         // caller data, matched by expireWhere()
+//     check() {},                   // throw a CollabError to refuse a decision now (e.g. offline)
+//     onDecide(decision, by) {},    // 'allow' | 'deny' | 'allow_all'; by = 'button' | 'text'
+//     mapDecision(decision) {},     // optional: the decision actually applied (card state, decision, onDecide),
+//                                   // e.g. a text 'allow_all' becomes 'allow' when the asker has no allow-all
+//   });
+//   await decision;                 // 'allow' | 'deny' | 'allow_all' | 'expired'
+import { forMember, mentions } from './mentions.mjs';
+import { CollabError, publicMessage } from './store.mjs';
+
+const STATES = { allow: 'allowed', deny: 'denied', allow_all: 'allowed_all' };
+// Labels and order of cc-connect's permission buttons (bridge core/engine.go), so
+// a DSH member's card reads the same as a cloud-web bot's.
+export const DEFAULT_ACTIONS = [
+  { decision: 'allow', label: '允许' },
+  { decision: 'deny', label: '拒绝' },
+  { decision: 'allow_all', label: '允许所有 (本次会话)' },
+];
+// Same vocabularies and order as bridge core/engine.go approveAllPhrases /
+// approveAllSingleTokens / allowKeywords / denyKeywords, so a text reply and a
+// button click resolve to the same decision.
+const APPROVE_ALL_PHRASES = ['allow all', 'approve all', 'yes all'];
+const APPROVE_ALL_TOKENS = ['allowall', '允许所有', '允许全部', '全部允许', '所有允许', '都允许', '全部同意'];
+const ALLOW_TOKENS = ['allow', 'yes', 'y', 'ok', 'approve', '允许', '同意', '可以', '好', '好的', '是', '确认'];
+const DENY_TOKENS = ['deny', 'no', 'n', 'reject', 'cancel', '拒绝', '不允许', '不行', '不', '否', '取消'];
+
+export class ChannelApprovals {
+  constructor(hub) {
+    this.hub = hub;
+    /** card message id -> { room, author, meta, check, onDecide, resolve } while undecided */
+    this.pending = new Map();
+    /**
+     * Owner message row -> Set of member ids its text answered or was withheld from.
+     * The DSH planner and the cloud-web listener both ask about the same row
+     * object (hub.post hands both the one row), so it is answered once.
+     */
+    this.answers = new WeakMap();
+    hub.approvals = this;
+  }
+
+  /** The hub's shared instance, created on first use. */
+  static of(hub) { return hub.approvals ?? new ChannelApprovals(hub); }
+
+  /**
+   * Post a pending permission card in `room` as `author` and register it.
+   * @returns { messageId, decision } — decision settles with the owner's choice, or 'expired'.
+   */
+  open({ room, author, text, actions = DEFAULT_ACTIONS, signal, meta, check, onDecide, mapDecision }) {
+    const card = { kind: 'permission', title: '权限请求', state: 'pending', actions: actions.map(a => ({ decision: a.decision, label: a.label })) };
+    const { message } = this.hub.post(room, { authorKind: 'role', author: author.id, name: author.name, text, card: JSON.stringify(card) });
+    let resolve;
+    const decision = new Promise(r => { resolve = r; });
+    this.pending.set(message.id, { room, author: author.id, meta, check, onDecide, mapDecision, resolve });
+    if (signal !== undefined) {
+      const onAbort = () => this.expire(message.id);
+      if (signal.aborted) onAbort();
+      else {
+        signal.addEventListener('abort', onAbort, { once: true });
+        decision.then(() => signal.removeEventListener('abort', onAbort));
+      }
+    }
+    return { messageId: message.id, decision };
+  }
+
+  /**
+   * Resolve card `msgId` with `decision` on behalf of the owner (callers check
+   * that). Throws CollabError when the message is not a permission card, is
+   * already decided or expired, or its asker refuses (check()).
+   */
+  decide(msgId, decision, by = 'button') {
+    if (!Object.hasOwn(STATES, decision)) throw new CollabError('invalid', `unknown decision ${decision}`);
+    const row = this.hub.store.message(msgId);
+    const card = row === undefined ? undefined : parseCard(row.card);
+    if (card?.kind !== 'permission') throw new CollabError('not-permission', '这条消息不是权限请求');
+    if (card.state !== 'pending') throw new CollabError('conflict', card.state === 'expired' ? '这个权限请求已过期' : '这个权限请求已经处理过了');
+    const p = this.pending.get(msgId);
+    if (p === undefined) {
+      // Pending in the store but not in memory: collab restarted, the asker's side is gone.
+      this.close(msgId, 'expired', row);
+      throw new CollabError('conflict', '这个权限请求已过期');
+    }
+    p.check?.();
+    const applied = p.mapDecision?.(decision) ?? decision;
+    this.close(msgId, STATES[applied], row, by);
+    p.resolve(applied);
+    p.onDecide?.(applied, by);
+    return publicMessage(this.hub.store.message(msgId), this.hub.store);
+  }
+
+  /** Withdraw card `msgId`: it shows as expired and its decision settles 'expired'. */
+  expire(msgId) {
+    const p = this.pending.get(msgId);
+    this.close(msgId, 'expired');
+    p?.resolve('expired');
+  }
+
+  /** Expire every pending card whose entry matches pred({ room, author, meta }). */
+  expireWhere(pred) {
+    for (const [msgId, p] of [...this.pending]) if (pred(p)) this.expire(msgId);
+  }
+
+  /** Mark a card decided/expired and update it for browsers. */
+  close(msgId, state, row = this.hub.store.message(msgId), by) {
+    this.pending.delete(msgId);
+    const card = row === undefined ? undefined : parseCard(row.card);
+    if (card?.kind !== 'permission' || card.state !== 'pending') return;
+    const next = { ...card, state, ...(by ? { decided_by: by } : {}), decided_at: Math.floor(Date.now() / 1000) };
+    this.hub.edit(row.id, 'role', row.author, row.text, JSON.stringify(next));
+  }
+
+  /**
+   * Owner text reply → decision on the room's pending cards; returns the ids of
+   * the members that must not also get the text as a message (card answered,
+   * or withheld from them). Idempotent per message row.
+   *
+   * cc-connect checks a pending permission before its gate and before any
+   * mention rule (bridge core/engine.go handleMessage → handlePendingPermission,
+   * ahead of applyGate), and hub bots run with group_reply_all
+   * (core/setup_wizard.go), so every bot with a pending prompt that receives an
+   * allow/deny word acts on it. Hence: no @ → the decision applies to every
+   * pending card in the room; an @ → only the @'d members', and the other
+   * pending members are not sent the text so their cards stay open.
+   */
+  answerByText(msg) {
+    const memo = this.answers.get(msg);
+    if (memo !== undefined) return memo;
+    const answered = new Set();
+    this.answers.set(msg, answered);
+    if (msg.author_kind !== 'user') return answered;
+    const inRoom = [...this.pending].filter(([, p]) => p.room === msg.room_id);
+    if (inRoom.length === 0) return answered;
+    const members = this.hub.routable();
+    const mentioned = mentions(msg.text, members);
+    for (const [msgId, p] of inRoom) {
+      const to = this.hub.members.get(p.author) ?? { id: p.author, name: '' };
+      const decision = textDecision(forMember(msg.text, to, members));
+      if (decision === undefined) continue;
+      if (mentioned.size > 0 && !mentioned.has(p.author)) {
+        answered.add(p.author); // addressed to someone else: withhold it so this member doesn't approve
+        continue;
+      }
+      try { this.decide(msgId, decision, 'text'); } catch { continue; }
+      answered.add(p.author);
+    }
+    return answered;
+  }
+}
+
+export function parseCard(raw) {
+  if (typeof raw !== 'string') return undefined;
+  try { return JSON.parse(raw); } catch { return undefined; }
+}
+
+// Same rune set as bridge core/engine.go permissionTokenSeparator (whitespace plus these).
+const PERM_TOKEN_SEPARATORS = /[\s@＠,，.。!！?？:：;；()（）[\]【】"'“”‘’、·]+/u;
+
+/** Port of bridge core/engine.go isApproveAllResponse / isAllowResponse / isDenyResponse (checked in that order). */
+export function textDecision(text) {
+  const tokens = String(text).toLowerCase().trim().split(PERM_TOKEN_SEPARATORS).filter(Boolean);
+  if (tokens.length === 0) return undefined;
+  const joined = tokens.join(' ');
+  if (APPROVE_ALL_PHRASES.some(ph => joined === ph || ` ${joined} `.includes(` ${ph} `))) return 'allow_all';
+  if (tokens.some(t => APPROVE_ALL_TOKENS.includes(t))) return 'allow_all';
+  if (tokens.some(t => ALLOW_TOKENS.includes(t))) return 'allow';
+  if (tokens.some(t => DENY_TOKENS.includes(t))) return 'deny';
+  return undefined;
+}

package/collab/attachments.mjs

@@ -0,0 +1,144 @@
+// #144: files and images the owner attaches to a channel message.
+// Bytes are kept on disk (one file per attachment, named by a random id) and the
+// message row only stores {id, name, mime, size}. Bots receive them through the
+// cloud_web wire format they already understand (bridge/platform/cloud-web/protocol.go
+// wireImage / wireFile: base64 data + mime_type + file_name).
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CollabError, messageAttachments } from './store.mjs';
+
+const ID = /^[0-9a-f-]{36}$/;
+// Raster images are shown in the page and sent to bots as images; anything else
+// (svg, bmp, heic, tiff, html, ...) is served as a download and sent as a file,
+// since model APIs only take png/jpeg/gif/webp images (Anthropic Messages API
+// image block media_type; others reject the request with 400).
+export const INLINE_IMAGE = /^image\/(png|jpeg|gif|webp)$/;
+// Larger images go to bots as files: Anthropic's Messages API rejects an image
+// over 5 MB (docs "Vision" / image size limits).
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+
+export class Attachments {
+  constructor(dir) { this.dir = dir; }
+
+  /** Save [{name, mime, data(base64)}] from a POST body; returns the metadata to store on the message. */
+  save(list) {
+    if (list == null) return [];
+    if (!Array.isArray(list)) throw new CollabError('invalid', 'attachments must be a list');
+    if (list.length) mkdirSync(this.dir, { recursive: true });
+    return list.map((item) => {
+      const data = Buffer.from(String(item?.data ?? ''), 'base64');
+      if (data.length === 0) throw new CollabError('invalid', 'attachment is empty');
+      const id = randomUUID();
+      writeFileSync(join(this.dir, id), data);
+      const name = String(item?.name ?? '').replace(/[\\/]/g, '_').slice(0, 200) || id;
+      const mime = String(item?.mime ?? '') || 'application/octet-stream';
+      return { id, name, mime, size: data.length };
+    });
+  }
+
+  /** The stored bytes of one attachment, or undefined. */
+  read(id) {
+    if (!ID.test(String(id))) return undefined;
+    try { return readFileSync(join(this.dir, id)); } catch { return undefined; }
+  }
+
+  /** cloud_web inbound frame fields (images / files) for a message's attachments. */
+  wire(metas) {
+    const images = [];
+    const files = [];
+    for (const a of metas ?? []) {
+      const bytes = this.read(a.id);
+      if (bytes === undefined) continue;
+      const item = { mime_type: a.mime, data: bytes.toString('base64'), file_name: a.name };
+      (INLINE_IMAGE.test(a.mime) && bytes.length <= MAX_IMAGE_BYTES ? images : files).push(item);
+    }
+    const out = {};
+    if (images.length) out.images = images;
+    if (files.length) out.files = files;
+    return out;
+  }
+}
+
+/** Shared wire admission, projected into the ACP prompt format, each block with its file name. */
+export function namedAttachmentBlocks(files, messages) {
+  const wire = files?.wire(messages.flatMap(messageAttachments)) ?? {};
+  return [
+    ...(wire.images ?? []).map(a => ({ name: a.file_name, block: { type: 'image', data: a.data, mimeType: a.mime_type } })),
+    ...(wire.files ?? []).map(a => ({ name: a.file_name, block: { type: 'resource', resource: {
+      uri: `attachment:///${encodeURIComponent(a.file_name)}`, mimeType: a.mime_type, blob: a.data,
+    } } })),
+  ];
+}
+
+export function attachmentBlocks(files, messages) {
+  return namedAttachmentBlocks(files, messages).map(b => b.block);
+}
+
+/**
+ * Native DSH requires durable attachment references, not inline ACP blocks.
+ * DSH validates the images as one batch (count, total bytes, type, pixels) and its
+ * error does not say which image failed, so when the batch is refused each block is
+ * re-admitted on top of the ones already accepted: an image DSH refuses on its own or
+ * that would push the batch over a limit is dropped, the rest are still delivered.
+ * Admission is content-addressed, so re-admitting the same bytes stores nothing new.
+ * Returns { parts, dropped: [{ name, reason, code? }] }.
+ */
+export async function nativeAttachmentBlocks(attachments, named) {
+  const dropped = [];
+  const parts = [];
+  const reason = err => String(err?.message ?? err);
+  const code = err => (typeof err?.code === 'string' ? err.code : undefined);
+  for (const { name, block: b } of named) {
+    if (b.type === 'image') { parts.push({ name, part: { type: 'image', mediaType: b.mimeType, data: b.data } }); continue; }
+    try {
+      parts.push({ name, part: { type: 'file', attachment: await attachments.admitEncodedFile({
+        data: b.resource.blob, name: decodeURIComponent(b.resource.uri.slice('attachment:///'.length)),
+      }) } });
+    } catch (err) { dropped.push({ name, reason: reason(err), code: code(err) }); }
+  }
+  if (parts.length === 0) return { parts: [], dropped };
+  try {
+    return { parts: await attachments.admitPromptContent(parts.map(p => p.part)), dropped };
+  } catch (batchErr) {
+    if (parts.length === 1) return { parts: [], dropped: [...dropped, { name: parts[0].name, reason: reason(batchErr), code: code(batchErr) }] };
+  }
+  const kept = [];
+  let admitted = [];
+  for (const p of parts) {
+    try {
+      admitted = await attachments.admitPromptContent([...kept, p.part]);
+      kept.push(p.part);
+    } catch (err) { dropped.push({ name: p.name, reason: reason(err), code: code(err) }); }
+  }
+  return { parts: admitted, dropped };
+}
+
+// DSH's attachment errors (dsh-attachment-local AttachmentError: English message + code).
+// The channel's system notes are Chinese, so the reason shown there is translated by code,
+// falling back to the exact English message, then to the original text.
+const UNDELIVERED_ZH = {
+  IMAGE_TOO_MANY_PIXELS: '图片太大，超过像素上限',
+  IMAGE_DIMENSION_TOO_LARGE: '图片太长或太宽，超过单边像素上限',
+  IMAGE_TOO_LARGE: '图片文件太大，超过大小上限',
+  INVALID_IMAGE: '图片格式不支持或已损坏',
+  IMAGE_TYPE_MISMATCH: '图片实际格式和扩展名/类型不符',
+  ATTACHMENT_NOT_FOUND: '附件文件找不到了',
+  ATTACHMENT_CORRUPT: '附件校验失败，可能已损坏',
+  ATTACHMENT_READ_FAILED: '附件读取失败',
+  ATTACHMENT_WRITE_FAILED: '附件处理失败',
+  INVALID_ATTACHMENT_REF: '附件引用无效',
+};
+const UNDELIVERED_MESSAGE_CODE = {
+  'Image exceeds the configured decoded-pixel limit.': 'IMAGE_TOO_MANY_PIXELS',
+  'Image exceeds the configured per-side pixel limit.': 'IMAGE_DIMENSION_TOO_LARGE',
+  'Image exceeds the configured byte limit.': 'IMAGE_TOO_LARGE',
+  'Unsupported or malformed image data.': 'INVALID_IMAGE',
+  'Image is empty.': 'INVALID_IMAGE',
+  'Declared image type does not match its bytes.': 'IMAGE_TYPE_MISMATCH',
+};
+
+/** Chinese reason for a dropped attachment ({ reason, code? } from nativeAttachmentBlocks). */
+export function undeliveredReasonZh({ reason, code }) {
+  return UNDELIVERED_ZH[code] ?? UNDELIVERED_ZH[UNDELIVERED_MESSAGE_CODE[String(reason).trim()]] ?? reason;
+}

package/collab/avatar-uploads.mjs

@@ -0,0 +1,53 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CollabError } from './store.mjs';
+
+export const UPLOAD_FILE = /^[a-z0-9-]+\.png$/;
+export const MAX_AVATAR_BYTES = 256 * 1024;
+const SIGNATURE = Buffer.from('89504e470d0a1a0a', 'hex');
+
+/** Local portraits; only validated filenames ever reach the filesystem. */
+export class AvatarUploads {
+  constructor(dir) { this.dir = dir; }
+
+  filename(id) {
+    const file = `${id}.png`;
+    if (!UPLOAD_FILE.test(file)) throw new CollabError('invalid', '头像文件名无效');
+    return file;
+  }
+
+  save(id, png) {
+    const file = this.filename(id);
+    if (typeof png !== 'string' || !png || (png.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(png))) {
+      throw new CollabError('invalid', '头像必须是有效的 PNG base64 数据（不含 data: 前缀）');
+    }
+    const bytes = Buffer.from(png, 'base64');
+    if (bytes.length > MAX_AVATAR_BYTES) throw new CollabError('invalid', '头像不能超过 256KB');
+    if (bytes.length < 33 || !bytes.subarray(0, 8).equals(SIGNATURE) || bytes.readUInt32BE(8) !== 13 || bytes.toString('ascii', 12, 16) !== 'IHDR') {
+      throw new CollabError('invalid', '头像必须是 PNG 图片');
+    }
+    if (bytes.readUInt32BE(16) !== 256 || bytes.readUInt32BE(20) !== 256) throw new CollabError('invalid', '头像尺寸必须是 256×256 像素');
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    const temporary = join(this.dir, `${file}.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temporary, bytes, { mode: 0o600, flag: 'wx' });
+      renameSync(temporary, join(this.dir, file));
+    } finally {
+      try { unlinkSync(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    return `upload:${file}`;
+  }
+
+  read(file) {
+    if (!UPLOAD_FILE.test(file)) return undefined;
+    try { return readFileSync(join(this.dir, file)); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+  }
+
+  remove(id) {
+    // Older member ids may contain underscores; those members never had an upload.
+    const file = `${id}.png`;
+    if (!UPLOAD_FILE.test(file)) return;
+    try { unlinkSync(join(this.dir, file)); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+}

package/collab/avatars.mjs

@@ -10,7 +10,7 @@ export const MAX_AVATAR_URL = 2048;
 /** Normalize a member avatar: '' (initial badge), a built-in slug, or — when allowUrl — an http(s) URL. Throws on anything else. */
 export function checkAvatar(value, { allowUrl = false } = {}) {
   const v = String(value ?? '').trim();
-  if (v === '' || AVATARS.includes(v)) return v;
+  if (v === '' || AVATARS.includes(v) || /^upload:[a-z0-9-]+\.png$/.test(v)) return v;
   if (allowUrl && v.length <= MAX_AVATAR_URL && /^https?:\/\/[^\s"'<>]+$/.test(v)) return v;
   throw new Error(`avatar must be one of ${AVATARS.join(', ')}${allowUrl ? ' or an http(s) URL' : ''}`);
 }

package/collab/cli-member.mjs

@@ -1,6 +1,7 @@
 // CLI 成员：把本机 claude / codex / gemini 通过 ACP 适配器接成群成员。
 // 每个（成员, 房间）一个 ACP session；ask(text) 返回该轮 agent_message_chunk 拼接文本。
 import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
 import { Readable, Writable } from 'node:stream'
 import { createRequire } from 'node:module'
 import path from 'node:path'
@@ -15,6 +16,26 @@ const ADAPTERS = {
   gemini: { cmd: 'gemini', args: ['--acp'] },
 }
 
+// DSH 原生权限档位：与 DSH 预设同名（@deepseek-ai/dsh-base cordis.patch.yml:264-276 预设表；
+// UI 名见 @deepseek-ai/dsh-client-ui-permission-presets README.zh.md:32）。默认档 = DSH 默认
+// workspace-write（dsh-base cordis.patch.yml:243-262：DSH_PERMISSION_MODE ?? 'workspace-write'）。
+// collab 运行时拿不到 DSH 包里的常量（DSH 由宿主提供），故照抄。
+export const PERMISSION_PRESETS = ['read-only', 'workspace-write', 'danger-full-access']
+export const DEFAULT_PERMISSION_PRESET = 'workspace-write'
+
+/**
+ * 按档位决定一条 ACP 权限请求：返回 { optionId }（直接答）或 'ask'（发审批卡）。
+ * danger-full-access = DSH approval never：不弹窗直接放行；workspace-write = approval ask：问用户；
+ * read-only：只读档下 CLI 的工具调用（ACP 只在要动手时才来问）一律拒。
+ */
+export function presetDecision(preset, options) {
+  const p = PERMISSION_PRESETS.includes(preset) ? preset : DEFAULT_PERMISSION_PRESET
+  if (p === 'workspace-write') return 'ask'
+  const want = p === 'danger-full-access' ? ['allow_once', 'allow_always'] : ['reject_once', 'reject_always']
+  const o = want.map((k) => options.find((x) => x.kind === k)).find(Boolean)
+  return o ? { optionId: o.optionId } : null
+}
+
 function resolveBin(pkg) {
   try {
     const pj = require.resolve(`${pkg}/package.json`)
@@ -25,8 +46,11 @@ function resolveBin(pkg) {
   return { cmd: 'npx', args: ['-y', pkg] }
 }
 
-function cleanEnv(env = process.env) {
-  return Object.fromEntries(Object.entries(env).filter(([k]) => !k.startsWith('CLAUDECODE') && !k.startsWith('CLAUDE_CODE_')))
+// 去掉外层 Claude Code 会话的标记（CLAUDECODE、CLAUDE_CODE_ENTRYPOINT…），成员的 claude 才不会当成嵌套会话；
+// 登录用的 CLAUDE_CODE_OAUTH_TOKEN 留着（ANTHROPIC_API_KEY 本来就不在过滤范围），只靠环境变量登录的用户才登得上。
+const KEEP_ENV = new Set(['CLAUDE_CODE_OAUTH_TOKEN'])
+export function cleanEnv(env = process.env) {
+  return Object.fromEntries(Object.entries(env).filter(([k]) => KEEP_ENV.has(k) || (!k.startsWith('CLAUDECODE') && !k.startsWith('CLAUDE_CODE_'))))
 }
 
 export class CliMember {
@@ -36,13 +60,42 @@ export class CliMember {
     this.cwd = cwd || process.cwd()
     this.persona = persona
     this.extraEnv = env || {}
-    this.sessions = new Map() // room -> { sessionId, first }
+    this.sessions = new Map() // room -> { sessionId }（当前 ACP 进程里活着的会话）
+    this.saved = new Map() // room -> sessionId：进程退出后留着，下次用 loadSession 续上
     this.buffers = new Map() // sessionId -> string
+    this.toolSince = new Set() // sessionId：上一段话之后有过工具调用
     this.onText = new Map() // sessionId -> (textSoFar) => void（#121 流式）
+    this.onTool = new Map() // sessionId -> (update) => void：tool_call / tool_call_update / agent_thought_chunk，给进度卡
+    this.onPermission = new Map() // sessionId -> async (request) => ACP outcome：本轮的审批处理器
     this.queue = new Map() // room -> Promise（同房间串行）
     this.ready = null
   }
 
+  /** ACP Client 回调（单独拆出来便于测试）。 */
+  _client() {
+    return {
+      requestPermission: async (r) => {
+        // 没有处理器（不在某一轮里）就没有地方问：按 DSH 无应答者的处理当取消（dsh-acp lib/index.js:1202-1228）。
+        const h = this.onPermission.get(r.sessionId)
+        return { outcome: h ? await h(r) : { outcome: 'cancelled' } }
+      },
+      sessionUpdate: async (n) => {
+        const u = n.update
+        if (u?.sessionUpdate === 'agent_message_chunk' && u.content?.type === 'text' && this.buffers.has(n.sessionId)) {
+          // 工具调用隔开的两段话是两条消息：另起一段，[report]/[ask] 这类首行标记才落在行首（team-exit.mjs exitMark）。
+          const prev = this.buffers.get(n.sessionId)
+          const gap = this.toolSince.has(n.sessionId) && prev.trim() && !/\n\s*$/.test(prev) ? '\n\n' : ''
+          this.toolSince.delete(n.sessionId)
+          const full = prev + gap + u.content.text
+          this.buffers.set(n.sessionId, full)
+          this.onText.get(n.sessionId)?.(full)
+        }
+        if (u?.sessionUpdate === 'tool_call' && this.buffers.has(n.sessionId)) this.toolSince.add(n.sessionId)
+        if ((u?.sessionUpdate === 'tool_call' || u?.sessionUpdate === 'tool_call_update' || u?.sessionUpdate === 'agent_thought_chunk') && this.buffers.has(n.sessionId)) this.onTool.get(n.sessionId)?.(u)
+      },
+    }
+  }
+
   _start() {
     if (this.ready) return this.ready
     const a = ADAPTERS[this.cli]
@@ -53,74 +106,106 @@ export class CliMember {
       env: { ...cleanEnv(), ...this.extraEnv },
     })
     this.proc = proc
-    const client = {
-      async requestPermission(r) {
-        const o = r.options.find((x) => x.kind?.startsWith('allow')) || r.options[0]
-        return { outcome: { outcome: 'selected', optionId: o.optionId } }
-      },
-      sessionUpdate: async (n) => {
-        const u = n.update
-        if (u?.sessionUpdate === 'agent_message_chunk' && u.content?.type === 'text' && this.buffers.has(n.sessionId)) {
-          const full = this.buffers.get(n.sessionId) + u.content.text
-          this.buffers.set(n.sessionId, full)
-          this.onText.get(n.sessionId)?.(full)
-        }
-      },
-    }
+    const client = this._client()
     const stream = acp.ndJsonStream(Writable.toWeb(proc.stdin), Readable.toWeb(proc.stdout))
     this.conn = new acp.ClientSideConnection(() => client, stream)
     const exited = new Promise((_, rej) => {
-      proc.once('error', rej)
-      proc.once('exit', (code) => { this.ready = null; rej(new Error(`${this.cli} acp exited: ${code}`)) })
+      proc.once('error', cause => {
+        this.ready = null
+        this.exited = null
+        if (existsSync(this.cwd)) return rej(cause)
+        const error = new Error(`CLI ${this.cli} 在目录 ${this.cwd} 无法启动：${cause.message}`, { cause })
+        error.code = 'COLLAB_CLI_START'
+        error.cwd = this.cwd
+        error.cli = this.cli
+        rej(error)
+      })
+      proc.once('exit', (code) => {
+        this.ready = null
+        // 会话 id 留到 saved，新进程起来后用 loadSession 续上（不支持时由调用方提示频道）。
+        for (const [room, s] of this.sessions) this.saved.set(room, s.sessionId)
+        this.sessions.clear()
+        rej(new Error(`${this.cli} acp exited: ${code}`))
+      })
     })
     exited.catch(() => {})
     this.exited = exited
     this.ready = Promise.race([
       this.conn.initialize({ protocolVersion: acp.PROTOCOL_VERSION, clientCapabilities: {} }),
       exited,
-    ])
+    ]).then((init) => { this.canLoad = init?.agentCapabilities?.loadSession === true; return init })
     return this.ready
   }
 
-  async _session(room) {
+  /**
+   * 房间的 ACP 会话。resumeId 是上次存下的 sessionId（bindings 里的）：CLI 声明了
+   * agentCapabilities.loadSession 就用 session/load 续上；不支持或续失败就开新会话，
+   * 返回 lost: true，由调用方在频道里说明上下文没了。
+   */
+  async _session(room, resumeId) {
     let s = this.sessions.get(room)
-    if (s) return s
+    if (s) return { ...s, resumed: false, lost: false }
     await this._start()
+    const prevId = resumeId || this.saved.get(room)
+    this.saved.delete(room)
+    if (prevId && this.canLoad) {
+      try {
+        await Promise.race([this.conn.loadSession({ sessionId: prevId, cwd: this.cwd, mcpServers: [] }), this.exited])
+        s = { sessionId: prevId }
+        this.sessions.set(room, s)
+        return { ...s, resumed: true, lost: false }
+      } catch (err) {
+        if (!this.ready) throw err // 进程在 load 时退出：照常报错
+      }
+    }
     const r = await Promise.race([this.conn.newSession({ cwd: this.cwd, mcpServers: [] }), this.exited])
-    s = { sessionId: r.sessionId, first: true }
+    s = { sessionId: r.sessionId }
     this.sessions.set(room, s)
-    return s
+    return { ...s, resumed: false, lost: Boolean(prevId) }
   }
 
-  /** onText(textSoFar) 在每个公开文字分片到达时调用（#121）。 */
-  ask(text, room = 'default', onText) {
+  /**
+   * onText(textSoFar) 在每个公开文字分片到达时调用（#121）；onTool(update) 在每个工具调用开始/更新和每个思考分片到达时调用。
+   * opts.resumeId：要续上的 sessionId；opts.onSession({ sessionId, resumed, lost })：会话就绪后、发提示词前调用。
+   * opts.attachments：随提示词发给 CLI 的 ACP 内容块（图片/音频/资源）。
+   * opts.onPermission(request)：本轮的 ACP session/request_permission 处理器，返回 ACP outcome。
+   */
+  ask(text, room = 'default', onText, onTool, opts = {}) {
     const prev = this.queue.get(room) || Promise.resolve()
-    const run = prev.catch(() => {}).then(() => this._ask(text, room, onText))
+    const run = prev.catch(() => {}).then(() => this._ask(text, room, onText, onTool, opts))
     this.queue.set(room, run)
     return run
   }
 
-  async _ask(text, room, onText) {
-    const s = await this._session(room)
-    const body = s.first && this.persona ? `${this.persona}\n\n${text}` : text
-    s.first = false
+  async _ask(text, room, onText, onTool, { resumeId, onSession, attachments = [], onPermission } = {}) {
+    const s = await this._session(room, resumeId)
+    await onSession?.(s)
+    // persona 每轮都拼：续上的或新开的会话都不会丢人设。
+    const body = this.persona ? `${this.persona}\n\n${text}` : text
     this.buffers.set(s.sessionId, '')
+    this.toolSince.delete(s.sessionId)
     if (onText) this.onText.set(s.sessionId, onText)
+    if (onTool) this.onTool.set(s.sessionId, onTool)
+    if (onPermission) this.onPermission.set(s.sessionId, onPermission)
     try {
       await Promise.race([
-        this.conn.prompt({ sessionId: s.sessionId, prompt: [{ type: 'text', text: body }] }),
+        this.conn.prompt({ sessionId: s.sessionId, prompt: [{ type: 'text', text: body }, ...attachments] }),
         this.exited,
       ])
       return this.buffers.get(s.sessionId)
     } finally {
       this.buffers.delete(s.sessionId)
+      this.toolSince.delete(s.sessionId)
       this.onText.delete(s.sessionId)
+      this.onTool.delete(s.sessionId)
+      this.onPermission.delete(s.sessionId)
     }
   }
 
   close() {
     this.proc?.kill()
     this.sessions.clear()
+    this.saved.clear()
     this.ready = null
   }
 }