[feature] askUserChoice 前端接入（ADR-0018）—— 接通 permission ask 路径

[mirror29]

想解决的问题

当前 `packages/orchestration/src/hooks/with-hooks.ts:154-162` 的 ask 路径没有前端实现——permission engine 返 `ask` 时只是返 `isError + "requires approval (ask path not yet wired; see ADR-0011)"`，agent 撞墙后只能让用户手动 curl/admin。

这导致 D-9 `paper.promote_candidate` 不得不用 workaround 走 `allow` + prompt 自检 + 后端硬校验代替 `ask` 拦截（见本次 promote 修复的 `permissions/defaults.ts` 注释 + `tools/strategy.ts` 文件头）。

长期影响：

• 任何"金融硬约束 — 人保留最终决定权"的 tool 都没有正式审批通道（promote、未来的实盘开关、risk config 修改等）
• `permissions/defaults.ts` 里 `ask` 列表（`live.submit_order(notional<1000)` / `risk.update_config`）实际等同于 deny + 提示，规则被悄悄改变

提议的方向

实现 ADR-0018 askUserChoice：

1. 后端：with-hooks 收到 `ask` 时挂起 tool 调用，发 SSE / WebSocket 事件到前端（包含 tool name + input + 调用理由）
2. 前端：CopilotKit / Mastra Studio 收到事件后弹气泡，用户点"允许 / 拒绝"
3. 回执：前端 POST `/api/permissions/{request_id}/respond`，后端拿到 decision 后恢复 tool 调用或抛 deny
4. 超时：30s 无响应默认 deny + audit log

回归路径：接通后把 `paper.promote_candidate` 从 `allow` 改回 `ask`（见 `permissions/defaults.ts` 现有注释 TODO）。

这个建议属于哪个 Phase？

• D-8b（持久化 trade_plans / approval_tokens）—— 同期接入合理
• D-9
• D-10 及之后
• 不确定 / 需要讨论

是否破坏现有约束？

• 只涉及 crypto 市场，不引入 A 股 / 美股逻辑
• 不让 LLM 获得直接下单路径 —— 反而增强人保留最终决定权
• 不动 `services/_shared/`
• 不引入与 AGPL-3.0 不兼容的依赖

其他

验收标准：

1. 把 `paper.promote_candidate` 临时回退到 `ask` 后，agent 调用时前端弹气泡
2. 用户允许 → tool 真执行；用户拒绝 → agent 收到清晰错误信息
3. 超时 / 用户关页面 → 默认 deny

关联：

• ADR-0011（permission engine）
• ADR-0018（askUserChoice 设计）
• 本次 promote 修复用 workaround 绕开了 ask 拦截
• `packages/orchestration/src/permissions/defaults.ts` 里 `paper.promote_candidate` 的注释 TODO

优先级判断：HIGH —— 长期阻塞所有"高危操作走 ask 审批门"的设计，当前 D-9 是临时绕开。

[mirror29]

D-9.1b 决议变更，关闭 issue

本 issue 提议"前端 SSE/WS + CopilotKit 弹气泡"方案接通 ask 路径。实测后路线变更——apps/web 远未起包 + CopilotKit Generative UI 接通成本不划算 + permission engine 的 ask 状态已能完整覆盖审批场景，前端组件方案被判定为不合理，已撤销。

实际交付的是会话驱动 ask 路径（ADR-0018 2026-05-28 修订）：

• permissionResolver 返 "ask" → with-hooks 拦截 → APPROVAL_REQUIRED: message 给 agent
• Agent 在 chat 转述 → 用户在 chat 自然语言回应（"同意 / 启用 / ok"）
• Agent 重调 → AskApprovalCache.consume 命中 → 一次性放行
• 配套 PendingApprovalsStore 作 audit / 异步审批口子（fire-and-forget timeout 30s）

D-9.1b 交付 commits

• a5d781b askUserChoice 后端接通
• 3808e50 ask 路径改会话驱动
• 8a2a429 死循环修复 + glob 通配 + 只读 tool 入 allow
• 3caef5c ask cache 用 stable JSON（DeepSeek key 顺序漂移）
• e76debd askCache 取 ctx.agent.threadId + 禁 UI 按钮捏造
• d28e3a7 permissions.default.yaml ↔ DEFAULT_PERMISSIONS 等价性
• 收尾打磨（2026-05-28）：telemetry emit + sessionId fallback warning + tryConsume 死代码删除 + e2e 集成测试 + orchestrator prompt 处理拒绝/含糊

验收（已通过）

• paper.promote_candidate 现在 permission=ask，agent 调用时返 requiresApproval=true ✅
• 用户在 chat 同意 → cache 命中 → tool 真执行 ✅
• 用户拒绝 / 含糊 → agent 不重调（orchestrator prompt 强制）+ cache TTL 60s 后自然过期 ✅
• 跨 session 隔离（A 用户的同意不被 B 用户复用）✅

关于"前端可视化审批面板"的明确不做

PendingApprovalsStore + GET /permissions/pending + POST /permissions/:id/respond HTTP API 保留作 审计 / 异步审批口子，但不做 apps/web 可视化面板（与前端组件方案被否决一致）。未来 CLI 监控工具或 scheduler cron 长任务异步审批可按需消费。

详见 ADR-0018 修订版（gitignored 内部文档）。

Closing as completed via alternative path.