Support runtime guidance tool interrupts

docs/technical-architecture/12-runtime-guidance-queue.md

@@ -28,7 +28,7 @@
        -> UI 展示 pending chip
        -> 用户可编辑、删除、引导
        -> 引导: kind=guidance，绑定当前 run_id
-       -> Agent loop 下一轮开始前消费 guidance
+       -> Agent loop 在安全插入点消费 guidance
        -> guidance 以 display=false 的 user message 注入 model_messages
 ```
 
@@ -83,10 +83,10 @@ DELETE /api/sessions/{session_id}/input-queue/{item_id}
 
 ### Runtime 注入
 
-`LocalCodingAgent` 提供 `runtime_guidance_provider`，在每轮模型调用前消费 pending guidance：
+`LocalCodingAgent` 提供 `runtime_guidance_provider`，在 Agent loop 的安全边界消费 pending guidance：
 
 ```text
-agent loop boundary
+agent loop safe boundary
   -> consume_session_guidance(session_id, run_id)
   -> append hidden user message:
      <runtime-guidance>
@@ -96,7 +96,35 @@ agent loop boundary
   -> 继续模型调用
 ```
 
-这个注入点必须在 tool_result 已经写回之后、下一次模型调用之前，不能插在 tool_use 和 tool_result 中间。
+可用插入点：
+
+| 插入点 | 时机 | 处理策略 |
+|--------|------|----------|
+| `before_model` | 每次模型调用前 | 常规消费，适合上一轮工具完成后的补充 |
+| `before_tools` | 模型已经给出工具计划，但工具还没开始执行 | 运行时先为上一批未执行工具补 synthetic `tool_result`，标记为 `runtime_guidance_replan`，再注入 guidance，让模型重新判断是否继续原计划、调整参数或换计划 |
+| `during_tool_interrupted` | 工具已经开始执行，且用户引导明显要求停止、改目标、换参数、纠错 | 运行时给当前工具传入单工具 interrupt event，并通过 process registry 终止当前工具进程；当前工具结果落盘后注入 guidance，让模型重规划 |
+| `after_tool` | 工具执行期间或刚完成后收到补充型 guidance，或工具没有中间输出无法及时中断 | 保留当前工具结果，停止继续执行同批旧工具计划，注入 guidance 让模型判断继续、补充或重跑 |
+| `before_finish` | 模型准备给最终回复前 | 注入 guidance，让模型判断是修正最终输出、补充信息，还是转为后续任务 |
+
+约束：
+
+- 不把 guidance 插在 `tool_use` 和 `tool_result` 中间。
+- `before_tools` 不直接删除 assistant 的工具计划，而是补一组“未执行、被 runtime 跳过”的 tool result，保证 Anthropic/Bedrock 的消息顺序合法。
+- `during_tool_interrupted` 不复用整轮 run cancel event，而是构造“整轮取消 OR 当前工具中断”的组合 cancel event 传给当前工具，避免把用户引导误判成整轮取消。
+- 立即中断依赖工具合作：bash / python / Jupyter / 远端执行等接入 cancel_event 或 process registry 的工具可以被终止；纯同步且没有中间输出的工具只能在返回后进入 `after_tool` 重规划。
+
+### 引导策略判断
+
+前端不暴露复杂按钮，用户仍然只点击“引导”。系统内部按安全点自动处理：
+
+| 用户引导类型 | 默认策略 |
+|--------------|----------|
+| 工具未开始前的纠偏、改目标、改参数 | `before_tools` 重规划 |
+| 工具完成后的补充要求 | `before_model` 注入下一次模型调用 |
+| 即将结束前的格式、总结、补充输出要求 | `before_finish` 注入并继续一轮 |
+| 已经运行中的长工具纠偏 | 明显停止/改目标/纠错类引导触发 `during_tool_interrupted`；补充输出类引导进入 `after_tool` |
+
+模型负责在收到 `<runtime-guidance>` 后判断如何吸收：继续原计划、调整计划、说明冲突或转为后续任务；运行时只负责选择合法插入点和维护消息协议。
 
 ## 前端交互
 
@@ -120,6 +148,7 @@ agent loop boundary
 1. 同一个账号同时打开两个 session，分别运行任务，输入不会串台。
 2. A session 运行中切到 B session 输入，B 的输入只进入 B 的 queue。
 3. A session 运行中输入后刷新，pending chip 仍存在。
-4. 点击“引导”后，下一次模型调用前能消费 guidance，并在活动区记录注入事件。
-5. 点击停止后，对应 run 的进程和 pending queue 都被取消。
-6. 触发 compact 后，UI 仍能从 `display_messages` 回放完整历史；模型只使用 compact 后的 `model_messages`。
+4. 点击“引导”后，最近的安全插入点能消费 guidance，并在活动区记录注入事件。
+5. 如果 guidance 在工具执行前到达，旧工具计划不执行，并产生 `runtime_guidance_replan_before_tools` 活动事件。
+6. 点击停止后，对应 run 的进程和 pending queue 都被取消。
+7. 触发 compact 后，UI 仍能从 `display_messages` 回放完整历史；模型只使用 compact 后的 `model_messages`。