From 61cf452d5cf8ce74c30d989d8b8d05b3137a66a5 Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Thu, 2 Jul 2026 16:59:31 +0800
Subject: [PATCH 01/10] feat(planning): add plan approval gate before execution

Insert an approval step between planning Phase A and execution Phase B.
When planning is enabled, the assistant pauses after producing a plan so
the user can run it or reject it; rejecting refills the composer with the
original prompt so the user can refine and resend (the prompt stays the
single source of intent, avoiding conflict with goal stability).

- PlanApprovalState (oneshot + RAII guard) mirroring ToolApprovalState
- respond_plan_approval command; planning_approval_enabled config (default on)
- emit llm:plan-approval-resolved so the card is dismissed on any resolution
  (approve/reject/timeout/cancel), not just button clicks
- AiPlanApprovalDialog UI + settings toggle + i18n
- KNOWFORGE_DEBUG_PLANNING logs the final plan before Phase B
---
 src-tauri/src/lib.rs                    |   2 +
 src-tauri/src/llm/mod.rs                |  27 ++++
 src-tauri/src/llm/plan_approval.rs      | 149 ++++++++++++++++++++++
 src-tauri/src/llm/planning.rs           | 103 ++++++++++++++++
 src-tauri/src/vault_config.rs           |  18 +++
 src/components/AiConversationPanel.tsx  |  53 +++++++-
 src/components/AiLlmSettingsModal.tsx   |  28 +++++
 src/components/AiPlanApprovalDialog.css | 156 ++++++++++++++++++++++++
 src/components/AiPlanApprovalDialog.tsx |  73 +++++++++++
 src/locales/en.json                     |   6 +
 src/locales/zh.json                     |   6 +
 src/types/toolTypes.ts                  |  12 ++
 src/types/vaultAiConfig.ts              |   2 +
 src/utils/toolInvoke.ts                 |  13 ++
 14 files changed, 646 insertions(+), 2 deletions(-)
 create mode 100644 src-tauri/src/llm/plan_approval.rs
 create mode 100644 src/components/AiPlanApprovalDialog.css
 create mode 100644 src/components/AiPlanApprovalDialog.tsx

diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 7c4712f..293e949 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -1712,6 +1712,7 @@ pub fn run() {
         .manage(Arc::new(semantic_index::EmbeddingCache::new()))
         .manage(Arc::new(llm::LlmSessionState::default()))
         .manage(Arc::new(llm::approval::ToolApprovalState::new()))
+        .manage(Arc::new(llm::plan_approval::PlanApprovalState::new()))
         .manage(Arc::new(tools::ToolRegistry::new()))
         .manage(Arc::new(skills::SkillRegistry::new()))
         .manage(Arc::new(tokio::sync::Semaphore::new(skills::SKILL_CONCURRENCY)))
@@ -1747,6 +1748,7 @@ pub fn run() {
             llm::start_chat_stream,
             llm::abort_llm_stream,
             llm::respond_tool_approval,
+            llm::respond_plan_approval,
             llm::clear_conversation_approvals,
             list_ai_conversations,
             create_ai_conversation,
diff --git a/src-tauri/src/llm/mod.rs b/src-tauri/src/llm/mod.rs
index 2fd4d27..4d8b41d 100644
--- a/src-tauri/src/llm/mod.rs
+++ b/src-tauri/src/llm/mod.rs
@@ -2,6 +2,7 @@
 
 pub(crate) mod agent_loop;
 pub mod approval;
+pub mod plan_approval;
 pub(crate) mod context_guard;
 pub(crate) mod planning;
 pub(crate) mod provider;
@@ -809,6 +810,7 @@ pub async fn start_chat_stream(
     registry: State<'_, Arc<ToolRegistry>>,
     ctx_factory: State<'_, Arc<ToolContextFactory>>,
     approval: State<'_, Arc<approval::ToolApprovalState>>,
+    plan_approval: State<'_, Arc<plan_approval::PlanApprovalState>>,
     skills: State<'_, Arc<SkillRegistry>>,
     http_client: State<'_, Arc<reqwest::Client>>,
     embed_cache_state: State<'_, Arc<semantic_index::EmbeddingCache>>,
@@ -882,6 +884,7 @@ pub async fn start_chat_stream(
     let registry_arc = Arc::clone(registry.inner());
     let ctx_factory_arc = Arc::clone(ctx_factory.inner());
     let approval_arc = Arc::clone(approval.inner());
+    let plan_approval_arc = Arc::clone(plan_approval.inner());
     let workspace_root = root.clone();
     let conversation_id = args
         .conversation_id
@@ -1039,6 +1042,8 @@ pub async fn start_chat_stream(
                         loop_config,
                         conversation_id,
                         approval_arc,
+                        plan_approval_arc,
+                        ai.planning_approval_enabled,
                         memory_manager.clone(),
                     )
                     .await;
@@ -1239,6 +1244,28 @@ pub fn respond_tool_approval(
     approval.resolve(&args.approval_id, args.decision)
 }
 
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RespondPlanApprovalArgs {
+    pub approval_id: String,
+    /// "approve" | "reject"
+    pub decision: String,
+}
+
+/// 前端响应一次计划审批请求（执行 / 拒绝）。
+#[tauri::command]
+pub fn respond_plan_approval(
+    args: RespondPlanApprovalArgs,
+    plan_approval: State<'_, Arc<plan_approval::PlanApprovalState>>,
+) -> Result<(), String> {
+    let decision = match args.decision.as_str() {
+        "approve" => plan_approval::PlanDecision::Approve,
+        "reject" => plan_approval::PlanDecision::Reject,
+        other => return Err(format!("unknown plan approval decision: {other}")),
+    };
+    plan_approval.resolve(&args.approval_id, decision)
+}
+
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ClearConversationApprovalsArgs {
diff --git a/src-tauri/src/llm/plan_approval.rs b/src-tauri/src/llm/plan_approval.rs
new file mode 100644
index 0000000..409aef6
--- /dev/null
+++ b/src-tauri/src/llm/plan_approval.rs
@@ -0,0 +1,149 @@
+//! 计划审批状态（Phase A→B 之间的门控）。
+//!
+//! `run_planned_agent` 在 Phase A 生成计划后调用 [`PlanApprovalState::register`] 拿到
+//! receiver + [`PlanApprovalPendingGuard`]，emit `llm:plan-approval-request`，然后
+//! `tokio::time::timeout` + `tokio::select!` 等待。guard 在外层 cancel 导致 future 被 drop 时
+//! 自动 `discard_pending`，防止 sender 泄漏在 map 中。计划审批每次都问，不做会话级缓存。
+//!
+//! 仅提供"执行 / 拒绝"两态：计划是提示词的派生预览，不可编辑——用户若不认可应拒绝并
+//! 修改提示词重发，保持"提示词是唯一意图来源"，避免与目标稳定性等机制产生冲突。
+
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+
+use tokio::sync::oneshot;
+
+/// 前端对一次计划审批请求的决策。
+pub enum PlanDecision {
+    /// 按计划执行。
+    Approve,
+    /// 拒绝执行，丢弃整个请求。
+    Reject,
+}
+
+pub struct PlanApprovalState {
+    pending: Mutex<HashMap<String, oneshot::Sender<PlanDecision>>>,
+}
+
+/// RAII 守卫：drop 时清理 pending 条目，避免外层 cancel 把 sender 留在 map 里。
+/// `discard_pending` 对不存在的 id 是 no-op，所以 happy path（resolve 已 remove）也安全。
+pub struct PlanApprovalPendingGuard {
+    state: Arc<PlanApprovalState>,
+    approval_id: String,
+}
+
+impl Drop for PlanApprovalPendingGuard {
+    fn drop(&mut self) {
+        self.state.discard_pending(&self.approval_id);
+    }
+}
+
+impl Default for PlanApprovalState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl PlanApprovalState {
+    pub fn new() -> Self {
+        Self {
+            pending: Mutex::new(HashMap::new()),
+        }
+    }
+
+    /// 登记一个 pending 审批，返回 (approval_id, receiver, guard)。
+    /// approval_id 用 UUID v4 生成，无序无关联以防泄漏其他元信息。
+    /// guard 需由调用方持有直到 await 结束。
+    pub fn register(
+        self: &Arc<Self>,
+    ) -> (String, oneshot::Receiver<PlanDecision>, PlanApprovalPendingGuard) {
+        let approval_id = uuid::Uuid::new_v4().to_string();
+        let (tx, rx) = oneshot::channel();
+        {
+            let mut g = match self.pending.lock() {
+                Ok(g) => g,
+                Err(p) => p.into_inner(),
+            };
+            g.insert(approval_id.clone(), tx);
+        }
+        let guard = PlanApprovalPendingGuard {
+            state: self.clone(),
+            approval_id: approval_id.clone(),
+        };
+        (approval_id, rx, guard)
+    }
+
+    /// 前端响应：取出 sender 并 send。若 id 不存在或 receiver 已 drop，返回 Err。
+    pub fn resolve(&self, approval_id: &str, decision: PlanDecision) -> Result<(), String> {
+        let tx = {
+            let mut g = match self.pending.lock() {
+                Ok(g) => g,
+                Err(p) => p.into_inner(),
+            };
+            g.remove(approval_id)
+                .ok_or_else(|| format!("unknown approval_id: {approval_id}"))?
+        };
+        tx.send(decision)
+            .map_err(|_| "approval receiver dropped (timed out or cancelled)".to_string())
+    }
+
+    /// 超时或取消时清理 pending 项（receiver 已 drop，sender 留在 map 里会泄漏）。
+    pub fn discard_pending(&self, approval_id: &str) {
+        let mut g = match self.pending.lock() {
+            Ok(g) => g,
+            Err(p) => p.into_inner(),
+        };
+        g.remove(approval_id);
+    }
+
+    #[cfg(test)]
+    fn pending_len(&self) -> usize {
+        let g = match self.pending.lock() {
+            Ok(g) => g,
+            Err(p) => p.into_inner(),
+        };
+        g.len()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn register_then_resolve_delivers_approve() {
+        let state = Arc::new(PlanApprovalState::new());
+        let (id, rx, _guard) = state.register();
+        state.resolve(&id, PlanDecision::Approve).unwrap();
+        assert!(matches!(rx.await.unwrap(), PlanDecision::Approve));
+    }
+
+    #[tokio::test]
+    async fn resolve_delivers_reject() {
+        let state = Arc::new(PlanApprovalState::new());
+        let (id, rx, _guard) = state.register();
+        state.resolve(&id, PlanDecision::Reject).unwrap();
+        assert!(matches!(rx.await.unwrap(), PlanDecision::Reject));
+    }
+
+    #[tokio::test]
+    async fn resolve_unknown_id_errors() {
+        let state = PlanApprovalState::new();
+        let err = state.resolve("nope", PlanDecision::Approve).unwrap_err();
+        assert!(err.contains("unknown"));
+    }
+
+    #[tokio::test]
+    async fn guard_drop_cleans_pending_and_resolve_fails() {
+        let state = Arc::new(PlanApprovalState::new());
+        assert_eq!(state.pending_len(), 0);
+        let id = {
+            let (id, _rx, _guard) = state.register();
+            assert_eq!(state.pending_len(), 1);
+            id
+        };
+        assert_eq!(state.pending_len(), 0);
+        let err = state.resolve(&id, PlanDecision::Approve).unwrap_err();
+        assert!(err.contains("unknown"));
+    }
+}
diff --git a/src-tauri/src/llm/planning.rs b/src-tauri/src/llm/planning.rs
index d7c2256..8e65648 100644
--- a/src-tauri/src/llm/planning.rs
+++ b/src-tauri/src/llm/planning.rs
@@ -1,5 +1,6 @@
 use std::path::PathBuf;
 use std::sync::Arc;
+use std::time::Duration;
 
 use serde_json::{json, Value};
 use tauri::{AppHandle, Emitter};
@@ -7,11 +8,17 @@ use tokio_util::sync::CancellationToken;
 
 use super::agent_loop::{self, AgentLoopConfig, SharedMemoryManager};
 use super::approval::ToolApprovalState;
+use super::plan_approval::{PlanApprovalState, PlanDecision};
 use super::provider::LlmProvider;
 use super::LlmChatMessage;
 use crate::tools::context::ToolContextFactory;
 use crate::tools::registry::ToolRegistry;
 
+/// How long to wait for the user to act on a plan-approval request before
+/// degrading to auto-execution. Longer than the per-tool approval timeout
+/// (120s) since reviewing/editing a full plan takes more time.
+const PLAN_APPROVAL_TIMEOUT: Duration = Duration::from_secs(300);
+
 const PLANNING_SYSTEM_PROMPT: &str = "\
 Analyze the user's request carefully. Output a numbered plan listing the exact tool calls \
 you would make and why. Do NOT call any tools — only output the plan as plain text.\n\n\
@@ -85,6 +92,65 @@ pub(crate) fn emit_planning_done(app: &AppHandle, session_id: &str, plan_text: &
     );
 }
 
+/// Emit `llm:agent-done` when we short-circuit before the agent loop runs
+/// (e.g. the user rejected the plan), so the frontend clears its streaming state.
+fn emit_agent_done(app: &AppHandle, session_id: &str) {
+    let _ = app.emit("llm:agent-done", json!({ "sessionId": session_id }));
+}
+
+/// Emit when the approval gate concludes by ANY means (approve / reject / timeout /
+/// cancel), so the frontend dismisses the approval card. Interactive resolutions
+/// (button clicks) also clear it optimistically on the frontend; this covers the
+/// non-interactive paths (timeout auto-execute, cancel) where no click happens.
+fn emit_plan_approval_resolved(app: &AppHandle, session_id: &str) {
+    let _ = app.emit("llm:plan-approval-resolved", json!({ "sessionId": session_id }));
+}
+
+/// Outcome of the plan-approval gate between Phase A and Phase B.
+enum PlanGateOutcome {
+    /// Proceed to execution with the original plan.
+    Proceed,
+    /// User rejected the plan; abandon the request.
+    Reject,
+    /// Cancelled while waiting.
+    Cancelled,
+}
+
+/// Emit `llm:plan-approval-request` and wait for the user's decision.
+/// Timeout or a closed channel degrades to executing the plan —
+/// rejecting on timeout would silently drop the whole user request.
+async fn wait_for_plan_approval(
+    app: &AppHandle,
+    session_id: &str,
+    conversation_id: &str,
+    state: &Arc<PlanApprovalState>,
+    plan_text: &str,
+    cancel: &CancellationToken,
+) -> PlanGateOutcome {
+    let (approval_id, rx, _guard) = state.register();
+    let _ = app.emit(
+        "llm:plan-approval-request",
+        json!({
+            "sessionId": session_id,
+            "conversationId": conversation_id,
+            "approvalId": approval_id,
+            "planText": plan_text,
+        }),
+    );
+
+    let decision = tokio::select! {
+        res = tokio::time::timeout(PLAN_APPROVAL_TIMEOUT, rx) => res,
+        _ = cancel.cancelled() => return PlanGateOutcome::Cancelled,
+    };
+
+    match decision {
+        Ok(Ok(PlanDecision::Approve)) => PlanGateOutcome::Proceed,
+        Ok(Ok(PlanDecision::Reject)) => PlanGateOutcome::Reject,
+        // Elapsed (Err) or sender dropped (Ok(Err)): degrade to auto-execute.
+        Ok(Err(_)) | Err(_) => PlanGateOutcome::Proceed,
+    }
+}
+
 #[allow(clippy::too_many_arguments)]
 pub async fn run_planned_agent(
     app: AppHandle,
@@ -101,6 +167,8 @@ pub async fn run_planned_agent(
     config: AgentLoopConfig,
     conversation_id: String,
     approval_state: Arc<ToolApprovalState>,
+    plan_approval_state: Arc<PlanApprovalState>,
+    planning_approval_enabled: bool,
     memory_manager: SharedMemoryManager,
 ) -> String {
     // Phase A: Planning (no tools, text-only output)
@@ -130,7 +198,42 @@ pub async fn run_planned_agent(
         return String::new();
     }
 
+    // Plan-approval gate (between Phase A and Phase B). Skipped when disabled or
+    // when there is no real plan to review (too short → Phase A likely failed).
+    if planning_approval_enabled && plan_text.trim().len() >= MIN_PLAN_LENGTH {
+        let outcome = wait_for_plan_approval(
+            &app,
+            &session_id,
+            &conversation_id,
+            &plan_approval_state,
+            &plan_text,
+            &cancel,
+        )
+        .await;
+
+        // Dismiss the approval card no matter how the gate resolved — including
+        // timeout/cancel, where the user never clicked and the frontend would
+        // otherwise leave the card up covering the execution output.
+        emit_plan_approval_resolved(&app, &session_id);
+
+        match outcome {
+            PlanGateOutcome::Proceed => {}
+            PlanGateOutcome::Reject => {
+                emit_agent_done(&app, &session_id);
+                return String::new();
+            }
+            PlanGateOutcome::Cancelled => return String::new(),
+        }
+    }
+
     // Phase B: Execution (inject plan, normal agent loop)
+    if std::env::var("KNOWFORGE_DEBUG_PLANNING").is_ok() {
+        eprintln!(
+            "[planning] Phase B plan_text ({} chars):\n{}\n[planning] --- end plan ---",
+            plan_text.trim().len(),
+            plan_text.trim()
+        );
+    }
     let exec_messages = if plan_text.trim().len() >= MIN_PLAN_LENGTH {
         inject_plan_into_messages(&initial_messages, &plan_text)
     } else {
diff --git a/src-tauri/src/vault_config.rs b/src-tauri/src/vault_config.rs
index 5536002..619190a 100644
--- a/src-tauri/src/vault_config.rs
+++ b/src-tauri/src/vault_config.rs
@@ -223,6 +223,11 @@ pub struct AiConfig {
     pub tools_enabled: bool,
     #[serde(default)]
     pub planning_enabled: bool,
+    /// Gate the plan-approval step between Phase A (plan) and Phase B (execute).
+    /// Defaults to true so planning users review plans before execution; only
+    /// takes effect when `planning_enabled` is true.
+    #[serde(default = "default_planning_approval_enabled")]
+    pub planning_approval_enabled: bool,
     #[serde(default = "default_memory_enabled")]
     pub memory_enabled: bool,
     #[serde(default = "default_memory_reflection_mode")]
@@ -255,6 +260,10 @@ fn default_tools_enabled() -> bool {
     true
 }
 
+fn default_planning_approval_enabled() -> bool {
+    true
+}
+
 fn default_memory_enabled() -> bool {
     true
 }
@@ -276,6 +285,7 @@ impl Default for AiConfig {
             privacy: AiPrivacy::default(),
             tools_enabled: true,
             planning_enabled: false,
+            planning_approval_enabled: true,
             memory_enabled: true,
             memory_reflection_mode: default_memory_reflection_mode(),
         }
@@ -512,6 +522,7 @@ struct AiDiskPartial {
     privacy: Option<AiPrivacyPartial>,
     tools_enabled: Option<bool>,
     planning_enabled: Option<bool>,
+    planning_approval_enabled: Option<bool>,
     memory_enabled: Option<bool>,
     memory_reflection_mode: Option<String>,
 }
@@ -669,6 +680,7 @@ pub struct AiConfigPatch {
     pub privacy: Option<AiPrivacyPatch>,
     pub tools_enabled: Option<bool>,
     pub planning_enabled: Option<bool>,
+    pub planning_approval_enabled: Option<bool>,
     pub memory_enabled: Option<bool>,
     pub memory_reflection_mode: Option<String>,
 }
@@ -804,6 +816,7 @@ pub struct AiConfigForUi {
     pub privacy: AiPrivacy,
     pub tools_enabled: bool,
     pub planning_enabled: bool,
+    pub planning_approval_enabled: bool,
     pub memory_enabled: bool,
     pub memory_reflection_mode: String,
 }
@@ -950,6 +963,9 @@ fn merge_ai_from_disk_partial(mut cfg: AiConfig, partial: AiDiskPartial) -> AiCo
     if let Some(v) = partial.planning_enabled {
         cfg.planning_enabled = v;
     }
+    if let Some(v) = partial.planning_approval_enabled {
+        cfg.planning_approval_enabled = v;
+    }
     if let Some(v) = partial.memory_enabled {
         cfg.memory_enabled = v;
     }
@@ -1026,6 +1042,7 @@ fn to_ai_for_ui(ai: AiConfig) -> AiConfigForUi {
         privacy: ai.privacy,
         tools_enabled: ai.tools_enabled,
         planning_enabled: ai.planning_enabled,
+        planning_approval_enabled: ai.planning_approval_enabled,
         memory_enabled: ai.memory_enabled,
         memory_reflection_mode: ai.memory_reflection_mode,
     }
@@ -1299,6 +1316,7 @@ fn apply_ai_patch(cfg: &mut AiConfig, patch: AiConfigPatch) {
     }
     if let Some(v) = patch.tools_enabled { cfg.tools_enabled = v; }
     if let Some(v) = patch.planning_enabled { cfg.planning_enabled = v; }
+    if let Some(v) = patch.planning_approval_enabled { cfg.planning_approval_enabled = v; }
     if let Some(v) = patch.memory_enabled { cfg.memory_enabled = v; }
     if let Some(v) = patch.memory_reflection_mode { cfg.memory_reflection_mode = v; }
 }
diff --git a/src/components/AiConversationPanel.tsx b/src/components/AiConversationPanel.tsx
index aaf5792..b66b57d 100644
--- a/src/components/AiConversationPanel.tsx
+++ b/src/components/AiConversationPanel.tsx
@@ -21,8 +21,9 @@ import { VAULT_CONFIG_UPDATED_EVENT } from "../utils/vaultConfigBroadcast";
 import { markdownTreatAsKfPrivateForUi } from "../utils/kfPrivateMarkdown";
 import { PrivacyChangeOverlay } from "./PrivacyChangeOverlay";
 import { AiToolApprovalDialog } from "./AiToolApprovalDialog";
-import type { ApprovalRequest } from "../types/toolTypes";
-import { respondToolApproval } from "../utils/toolInvoke";
+import { AiPlanApprovalDialog } from "./AiPlanApprovalDialog";
+import type { ApprovalRequest, PlanApprovalRequest } from "../types/toolTypes";
+import { respondPlanApproval, respondToolApproval } from "../utils/toolInvoke";
 import { listSkills, invokeSkill } from "../utils/skillInvoke";
 import type { SkillManifestJson } from "../types/skillTypes";
 import { parseSlashCommand } from "../utils/parseSlashCommand";
@@ -419,6 +420,38 @@ export function AiConversationPanel() {
     setActiveApproval(null);
   }, [conversationId]);
 
+  /** 计划审批：Planning 模式每个 run 只有一份计划，无需队列 */
+  const [activePlanApproval, setActivePlanApproval] =
+    useState<PlanApprovalRequest | null>(null);
+  const handlePlanApprove = useCallback((approvalId: string) => {
+    void respondPlanApproval(approvalId, "approve").catch(() => {});
+    setActivePlanApproval(null);
+  }, []);
+  const handlePlanReject = useCallback((approvalId: string) => {
+    void respondPlanApproval(approvalId, "reject").catch(() => {});
+    setActivePlanApproval(null);
+    // 拒绝后把触发本次的提示词回填到输入框，方便用户修改后重发
+    // （提示词是唯一意图来源，改提示词而非改计划）。
+    setMessages((prev) => {
+      for (let i = prev.length - 1; i >= 0; i--) {
+        if (prev[i].role === "user") {
+          const lastUser = prev[i].content;
+          if (lastUser.length > 0) {
+            queueMicrotask(() => {
+              setInput(lastUser);
+              composerRef.current?.focus();
+            });
+          }
+          break;
+        }
+      }
+      return prev;
+    });
+  }, []);
+  useEffect(() => {
+    setActivePlanApproval(null);
+  }, [conversationId]);
+
   /** invite-after-answer 状态 */
   const [inviteData, setInviteData] = useState<InviteData | null>(null);
   const [challengeInlineData, setChallengeInlineData] = useState<ChallengeInlineData | null>(null);
@@ -1086,6 +1119,17 @@ export function AiConversationPanel() {
           return next;
         });
       }),
+      listen<PlanApprovalRequest>("llm:plan-approval-request", (e) => {
+        if (e.payload.sessionId !== activeSessionRef.current) return;
+        setActivePlanApproval(e.payload);
+      }),
+      // Gate resolved by any means (approve/reject/timeout/cancel) — dismiss the
+      // card. Covers non-interactive paths (timeout auto-execute) where the user
+      // never clicked, so the card would otherwise linger over the output.
+      listen<{ sessionId: string }>("llm:plan-approval-resolved", (e) => {
+        if (e.payload.sessionId !== activeSessionRef.current) return;
+        setActivePlanApproval(null);
+      }),
       listen<{ sessionId: string }>("llm:planning-start", (e) => {
         if (e.payload.sessionId !== activeSessionRef.current) return;
         setIsPlanning(true);
@@ -2657,6 +2701,11 @@ export function AiConversationPanel() {
       ) : null}
 
       <AiToolApprovalDialog request={activeApproval} onResolve={handleApprovalResolve} />
+      <AiPlanApprovalDialog
+        request={activePlanApproval}
+        onApprove={handlePlanApprove}
+        onReject={handlePlanReject}
+      />
     </section>
   );
 }
diff --git a/src/components/AiLlmSettingsModal.tsx b/src/components/AiLlmSettingsModal.tsx
index d9cf649..d8b4414 100644
--- a/src/components/AiLlmSettingsModal.tsx
+++ b/src/components/AiLlmSettingsModal.tsx
@@ -144,6 +144,7 @@ type FormState = {
   allowPrivateContentInLocalLlm: boolean;
   toolsEnabled: boolean;
   planningEnabled: boolean;
+  planningApprovalEnabled: boolean;
   memoryEnabled: boolean;
   memoryReflectionMode: string;
   passiveHighlightEnabled: boolean;
@@ -252,6 +253,7 @@ function defaultForm(): FormState {
     allowPrivateContentInLocalLlm: false,
     toolsEnabled: true,
     planningEnabled: false,
+    planningApprovalEnabled: true,
     memoryEnabled: true,
     memoryReflectionMode: "confirm",
     passiveHighlightEnabled: true,
@@ -302,6 +304,7 @@ function aiFormEqualsPersisted(a: FormState, b: FormState): boolean {
     "allowPrivateContentInLocalLlm",
     "toolsEnabled",
     "planningEnabled",
+    "planningApprovalEnabled",
     "memoryEnabled",
     "memoryReflectionMode",
     "passiveHighlightEnabled",
@@ -364,6 +367,7 @@ function vaultConfigToForm(cfg: VaultConfigForUi): FormState {
     allowPrivateContentInLocalLlm: ai.privacy.allowPrivateContentInLocalLlm,
     toolsEnabled: ai.toolsEnabled !== false,
     planningEnabled: ai.planningEnabled === true,
+    planningApprovalEnabled: ai.planningApprovalEnabled !== false,
     memoryEnabled: ai.memoryEnabled !== false,
     memoryReflectionMode: ai.memoryReflectionMode ?? "confirm",
     passiveHighlightEnabled: cognitive.passiveHighlightEnabled !== false,
@@ -781,6 +785,7 @@ export function AiLlmSettingsModal({
         },
         toolsEnabled: form.toolsEnabled,
         planningEnabled: form.planningEnabled,
+        planningApprovalEnabled: form.planningApprovalEnabled,
         memoryEnabled: form.memoryEnabled,
         memoryReflectionMode: form.memoryReflectionMode,
       },
@@ -1299,6 +1304,29 @@ export function AiLlmSettingsModal({
                 {t("settings.planningEnabled")}
               </label>
               <p className="app-modal__hint">{t("settings.planningEnabledHint")}</p>
+              {form.planningEnabled && (
+                <>
+                  <label
+                    className="ai-settings__check"
+                    title={t("settings.planningApprovalEnabledHint")}
+                  >
+                    <input
+                      type="checkbox"
+                      checked={form.planningApprovalEnabled}
+                      onChange={(e) =>
+                        setForm((f) => ({
+                          ...f,
+                          planningApprovalEnabled: e.target.checked,
+                        }))
+                      }
+                    />
+                    {t("settings.planningApprovalEnabled")}
+                  </label>
+                  <p className="app-modal__hint">
+                    {t("settings.planningApprovalEnabledHint")}
+                  </p>
+                </>
+              )}
               <label className="ai-settings__check" title={t("settings.memoryEnabledHint")}>
                 <input
                   type="checkbox"
diff --git a/src/components/AiPlanApprovalDialog.css b/src/components/AiPlanApprovalDialog.css
new file mode 100644
index 0000000..324d234
--- /dev/null
+++ b/src/components/AiPlanApprovalDialog.css
@@ -0,0 +1,156 @@
+.plan-approval-overlay {
+  position: absolute;
+  inset: 0;
+  z-index: 110;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.4);
+  backdrop-filter: blur(2px);
+}
+
+.plan-approval-overlay__card {
+  width: min(560px, calc(100% - 32px));
+  margin: 0 16px;
+  padding: 20px 22px;
+  background: #fff;
+  border-radius: 12px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  max-height: calc(100% - 32px);
+  overflow: hidden;
+}
+
+.plan-approval-overlay__header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.plan-approval-overlay__title {
+  margin: 0;
+  font-size: 0.95rem;
+  font-weight: 600;
+  color: #111827;
+}
+
+.plan-approval-overlay__description {
+  margin: 0;
+  font-size: 0.85rem;
+  line-height: 1.5;
+  color: #374151;
+}
+
+.plan-approval-overlay__plan {
+  padding: 10px 14px;
+  background: #f9fafb;
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  font-size: 0.85rem;
+  color: #1f2937;
+  overflow-y: auto;
+  flex: 1 1 auto;
+  min-height: 80px;
+  max-height: 45vh;
+}
+
+.plan-approval-overlay__actions {
+  display: flex;
+  flex-direction: row;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 4px;
+}
+
+.plan-approval-overlay__btn {
+  min-width: 90px;
+  padding: 7px 14px;
+  font-size: 0.8rem;
+  line-height: 1.4;
+  border-radius: 6px;
+  border: 1px solid transparent;
+  cursor: pointer;
+  transition: background 0.15s, box-shadow 0.15s;
+}
+
+.plan-approval-overlay__btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.plan-approval-overlay__btn--approve {
+  background: #2563eb;
+  color: #fff;
+  border-color: #1d4ed8;
+}
+
+.plan-approval-overlay__btn--approve:hover:not(:disabled) {
+  background: #1d4ed8;
+}
+
+.plan-approval-overlay__btn--approve:focus-visible {
+  outline: 2px solid #60a5fa;
+  outline-offset: 2px;
+}
+
+.plan-approval-overlay__btn--reject {
+  background: transparent;
+  color: #6b7280;
+  border-color: #d1d5db;
+  margin-right: auto;
+}
+
+.plan-approval-overlay__btn--reject:hover {
+  background: #f3f4f6;
+}
+
+.plan-approval-overlay__btn--reject:focus-visible {
+  outline: 2px solid #9ca3af;
+  outline-offset: 2px;
+}
+
+/* ---- dark mode ---- */
+@media (prefers-color-scheme: dark) {
+  .plan-approval-overlay {
+    background: rgba(0, 0, 0, 0.55);
+  }
+
+  .plan-approval-overlay__card {
+    background: #1f2937;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  }
+
+  .plan-approval-overlay__title {
+    color: #f3f4f6;
+  }
+
+  .plan-approval-overlay__description {
+    color: #d1d5db;
+  }
+
+  .plan-approval-overlay__plan {
+    background: #111827;
+    border-color: #374151;
+    color: #e5e7eb;
+  }
+
+  .plan-approval-overlay__btn--approve {
+    background: #3b82f6;
+    border-color: #2563eb;
+  }
+
+  .plan-approval-overlay__btn--approve:hover:not(:disabled) {
+    background: #2563eb;
+  }
+
+  .plan-approval-overlay__btn--reject {
+    color: #9ca3af;
+    border-color: #4b5563;
+  }
+
+  .plan-approval-overlay__btn--reject:hover {
+    background: rgba(255, 255, 255, 0.06);
+  }
+}
diff --git a/src/components/AiPlanApprovalDialog.tsx b/src/components/AiPlanApprovalDialog.tsx
new file mode 100644
index 0000000..92476db
--- /dev/null
+++ b/src/components/AiPlanApprovalDialog.tsx
@@ -0,0 +1,73 @@
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+
+import type { PlanApprovalRequest } from "../types/toolTypes";
+import { AiAssistantMarkdown } from "./AiAssistantMarkdown";
+import "./AiPlanApprovalDialog.css";
+
+interface AiPlanApprovalDialogProps {
+  request: PlanApprovalRequest | null;
+  onApprove: (approvalId: string) => void;
+  onReject: (approvalId: string) => void;
+}
+
+export function AiPlanApprovalDialog({
+  request,
+  onApprove,
+  onReject,
+}: AiPlanApprovalDialogProps) {
+  const { t } = useTranslation();
+
+  const approve = useCallback(() => {
+    if (request) onApprove(request.approvalId);
+  }, [request, onApprove]);
+
+  const reject = useCallback(() => {
+    if (request) onReject(request.approvalId);
+  }, [request, onReject]);
+
+  if (!request) return null;
+
+  return (
+    <div
+      className="plan-approval-overlay"
+      role="alertdialog"
+      aria-modal="true"
+      aria-label={t("aiPanel.planApprovalTitle")}
+    >
+      <div className="plan-approval-overlay__card">
+        <div className="plan-approval-overlay__header">
+          <h3 className="plan-approval-overlay__title">
+            {t("aiPanel.planApprovalTitle")}
+          </h3>
+        </div>
+
+        <p className="plan-approval-overlay__description">
+          {t("aiPanel.planApprovalDescription")}
+        </p>
+
+        <div className="plan-approval-overlay__plan">
+          <AiAssistantMarkdown content={request.planText} />
+        </div>
+
+        <div className="plan-approval-overlay__actions">
+          <button
+            type="button"
+            className="plan-approval-overlay__btn plan-approval-overlay__btn--reject"
+            onClick={reject}
+          >
+            {t("aiPanel.planApprovalReject")}
+          </button>
+          <button
+            type="button"
+            className="plan-approval-overlay__btn plan-approval-overlay__btn--approve"
+            onClick={approve}
+            autoFocus
+          >
+            {t("aiPanel.planApprovalRun")}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/locales/en.json b/src/locales/en.json
index 06ff4ba..ce30155 100644
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -332,6 +332,10 @@
     "toolApprovalPolicyLabel": "Approval scope",
     "toolApprovalPolicyOnce": "Once per conversation",
     "toolApprovalPolicyEach": "Each invocation",
+    "planApprovalTitle": "Review plan before running",
+    "planApprovalDescription": "The assistant produced an execution plan. Run it, or reject and refine your prompt before resending.",
+    "planApprovalRun": "Run",
+    "planApprovalReject": "Reject",
     "skillBadge": "Skill: {{name}}",
     "skillUnknown": "Unknown skill: {{id}}. Type / to see available skills, or use /skills to list them.",
     "skillInvokeFailed": "Failed to invoke skill: {{message}}",
@@ -501,6 +505,8 @@
     "planningSection": "Planning mode",
     "planningEnabled": "Enable planning before tool execution",
     "planningEnabledHint": "When enabled, the AI plans tool calls before executing them using the active provider.",
+    "planningApprovalEnabled": "Review plan before running",
+    "planningApprovalEnabledHint": "When enabled, the AI pauses after producing a plan so you can run, edit, or reject it. When off, the plan runs automatically.",
     "memoryEnabled": "Enable agent memory",
     "memoryEnabledHint": "When enabled, the AI remembers your knowledge domains, interaction style, and corrections across conversations to provide more personalized responses.",
     "clearMemory": "Clear all memory",
diff --git a/src/locales/zh.json b/src/locales/zh.json
index a1474ea..106496e 100644
--- a/src/locales/zh.json
+++ b/src/locales/zh.json
@@ -332,6 +332,10 @@
     "toolApprovalPolicyLabel": "审批范围",
     "toolApprovalPolicyOnce": "本会话仅询问一次",
     "toolApprovalPolicyEach": "每次调用都询问",
+    "planApprovalTitle": "执行前审核计划",
+    "planApprovalDescription": "助手已生成执行计划。可以直接执行；若不认可，请拒绝并修改提示词后重发。",
+    "planApprovalRun": "执行",
+    "planApprovalReject": "拒绝",
     "skillBadge": "技能：{{name}}",
     "skillUnknown": "未知技能：{{id}}。输入 / 查看可用技能，或用 /skills 列出全部。",
     "skillInvokeFailed": "调用技能失败：{{message}}",
@@ -501,6 +505,8 @@
     "planningSection": "规划模式",
     "planningEnabled": "工具执行前先做规划",
     "planningEnabledHint": "开启后，AI 在调用工具前会先制定计划，使用当前活跃的模型服务。",
+    "planningApprovalEnabled": "执行前审核计划",
+    "planningApprovalEnabledHint": "开启后，AI 生成计划会先暂停等待你确认，可执行、编辑后执行或拒绝。关闭则计划生成后自动执行。",
     "memoryEnabled": "启用 Agent 记忆",
     "memoryEnabledHint": "开启后，AI 会跨对话记住你的知识领域、交互风格和纠正信息，提供更个性化的回答。",
     "clearMemory": "清除全部记忆",
diff --git a/src/types/toolTypes.ts b/src/types/toolTypes.ts
index 74c8270..70a5f23 100644
--- a/src/types/toolTypes.ts
+++ b/src/types/toolTypes.ts
@@ -114,3 +114,15 @@ export interface ApprovalRequest {
   risk: Risk;
   effects: Effect[];
 }
+
+// 后端在 Planning 模式下、Phase A 生成计划后、Phase B 执行前 emit
+// `llm:plan-approval-request`，前端展示审批卡片；用户可执行或拒绝，
+// 通过 `respond_plan_approval` 回送。计划不可编辑——不认可应拒绝并修改提示词重发。
+export interface PlanApprovalRequest {
+  sessionId: string;
+  conversationId: string;
+  approvalId: string;
+  planText: string;
+}
+
+export type PlanApprovalDecision = "approve" | "reject";
diff --git a/src/types/vaultAiConfig.ts b/src/types/vaultAiConfig.ts
index 3669381..2fad7ce 100644
--- a/src/types/vaultAiConfig.ts
+++ b/src/types/vaultAiConfig.ts
@@ -41,6 +41,7 @@ export type AiConfigForUi = {
   privacy: AiPrivacy;
   toolsEnabled: boolean;
   planningEnabled: boolean;
+  planningApprovalEnabled: boolean;
   memoryEnabled: boolean;
   memoryReflectionMode: string;
 };
@@ -102,6 +103,7 @@ export type AiConfigSavePatch = {
   };
   toolsEnabled?: boolean;
   planningEnabled?: boolean;
+  planningApprovalEnabled?: boolean;
   memoryEnabled?: boolean;
   memoryReflectionMode?: string;
 };
diff --git a/src/utils/toolInvoke.ts b/src/utils/toolInvoke.ts
index 9c31cab..15af6d3 100644
--- a/src/utils/toolInvoke.ts
+++ b/src/utils/toolInvoke.ts
@@ -3,6 +3,7 @@
 
 import { invoke } from "@tauri-apps/api/core";
 import type {
+  PlanApprovalDecision,
   ToolManifestJson,
   ToolResultErr,
   ToolResultJson,
@@ -62,6 +63,18 @@ export async function respondToolApproval(
   return invoke<void>("respond_tool_approval", { args: { approvalId, decision } });
 }
 
+/**
+ * 回送计划审批结果（执行 / 拒绝）。
+ */
+export async function respondPlanApproval(
+  approvalId: string,
+  decision: PlanApprovalDecision,
+): Promise<void> {
+  return invoke<void>("respond_plan_approval", {
+    args: { approvalId, decision },
+  });
+}
+
 /**
  * 切换/删除会话时清理 ConfirmOncePerSession 会话级缓存。
  */

From 4ba760f6d4aa6162a4029a14b3775ce5c941effe Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Thu, 2 Jul 2026 17:38:52 +0800
Subject: [PATCH 02/10] fix(agent-loop): don't count approval wait against tool
 timeout

---
 src-tauri/src/llm/agent_loop.rs         | 84 +++++++++++++++++--------
 src/components/AiToolApprovalDialog.tsx |  2 +-
 2 files changed, 59 insertions(+), 27 deletions(-)

diff --git a/src-tauri/src/llm/agent_loop.rs b/src-tauri/src/llm/agent_loop.rs
index 5c61ab6..708db27 100644
--- a/src-tauri/src/llm/agent_loop.rs
+++ b/src-tauri/src/llm/agent_loop.rs
@@ -394,12 +394,29 @@ pub async fn run_agent_stream(
                 if skip {
                     return (Err(format!("loop detected: '{}' called too many times with same arguments", tc.name)), 0u64);
                 }
+                // Human-in-the-loop approval runs first, OUTSIDE tool_timeout — the
+                // time the user spends deciding must not count against the tool's
+                // execution budget (it has its own 30-min backstop + cancel).
+                if let Err(e) = await_tool_approval(
+                    &app,
+                    &session_id,
+                    &registry,
+                    &conversation_id,
+                    &tc,
+                    &approval_state,
+                    &cancel,
+                )
+                .await
+                {
+                    return (Err(e), 0u64);
+                }
                 let tool_timeout = registry
                     .get(&tc.name)
                     .and_then(|t| t.timeout_ms())
                     .map(Duration::from_millis)
                     .unwrap_or(default_tool_timeout);
                 let nesting_depth = config.nesting_depth;
+                // Measured after approval so the duration reflects execution only.
                 let exec_start = std::time::Instant::now();
                 let result = tokio::select! {
                     res = tokio::time::timeout(tool_timeout, execute_tool(
@@ -412,7 +429,6 @@ pub async fn run_agent_stream(
                         app_bundle_resource_dir,
                         &conversation_id,
                         &tc,
-                        &approval_state,
                         &cancel,
                         nesting_depth,
                         Some(provider),
@@ -695,22 +711,21 @@ where
     result
 }
 
+/// Human-in-the-loop approval gate for a tool call. Runs BEFORE and OUTSIDE the
+/// tool-execution timeout, so time the user spends deciding is not charged against
+/// the tool's execution budget (that timeout must only bound the actual invocation).
+/// Returns Ok(()) to proceed, or Err to abort (forbidden / denied / cancelled /
+/// approval backstop expired).
 #[allow(clippy::too_many_arguments)]
-pub(crate) async fn execute_tool(
+pub(crate) async fn await_tool_approval(
     app: &AppHandle,
     session_id: &str,
     registry: &Arc<ToolRegistry>,
-    ctx_factory: &Arc<ToolContextFactory>,
-    workspace_root: &PathBuf,
-    app_cache_dir: Option<PathBuf>,
-    app_bundle_resource_dir: Option<PathBuf>,
     conversation_id: &str,
     tc: &NormalizedToolCall,
     approval_state: &Arc<ToolApprovalState>,
     cancel: &CancellationToken,
-    nesting_depth: u8,
-    provider: Option<Arc<dyn LlmProvider>>,
-) -> Result<Value, String> {
+) -> Result<(), String> {
     let tool = registry
         .get(&tc.name)
         .ok_or_else(|| format!("tool not found: {}", tc.name))?;
@@ -723,14 +738,13 @@ pub(crate) async fn execute_tool(
         manifest_policy
     };
     match &policy {
-        ApprovalPolicy::Auto => { /* 直接放行 */ }
-        ApprovalPolicy::Forbidden => {
-            return Err(format!("tool '{}' is forbidden", tc.name));
-        }
+        ApprovalPolicy::Auto => Ok(()),
+        ApprovalPolicy::Forbidden => Err(format!("tool '{}' is forbidden", tc.name)),
         ApprovalPolicy::ConfirmOncePerSession
             if approval_state.is_pre_approved(conversation_id, &tc.name) =>
         {
             // 会话级缓存命中,放行
+            Ok(())
         }
         ApprovalPolicy::ConfirmEach | ApprovalPolicy::ConfirmOncePerSession => {
             let (approval_id, rx, _guard) = approval_state.register();
@@ -751,7 +765,7 @@ pub(crate) async fn execute_tool(
             );
 
             let decision = tokio::select! {
-                res = tokio::time::timeout(Duration::from_secs(120), rx) => res,
+                res = tokio::time::timeout(TOOL_APPROVAL_TIMEOUT, rx) => res,
                 _ = cancel.cancelled() => {
                     return Err("cancelled".to_string());
                 }
@@ -762,22 +776,34 @@ pub(crate) async fn execute_tool(
                     if matches!(policy, ApprovalPolicy::ConfirmOncePerSession) {
                         approval_state.remember_approval(conversation_id, &tc.name);
                     }
+                    Ok(())
                 }
-                Ok(Ok(false)) => {
-                    return Err(format!("user denied approval for tool '{}'", tc.name));
-                }
-                Ok(Err(_)) => {
-                    return Err("approval channel closed unexpectedly".to_string());
-                }
-                Err(_) => {
-                    return Err(format!(
-                        "approval timed out for tool '{}'",
-                        tc.name
-                    ));
-                }
+                Ok(Ok(false)) => Err(format!("user denied approval for tool '{}'", tc.name)),
+                Ok(Err(_)) => Err("approval channel closed unexpectedly".to_string()),
+                Err(_) => Err(format!("approval timed out for tool '{}'", tc.name)),
             }
         }
     }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn execute_tool(
+    app: &AppHandle,
+    session_id: &str,
+    registry: &Arc<ToolRegistry>,
+    ctx_factory: &Arc<ToolContextFactory>,
+    workspace_root: &PathBuf,
+    app_cache_dir: Option<PathBuf>,
+    app_bundle_resource_dir: Option<PathBuf>,
+    conversation_id: &str,
+    tc: &NormalizedToolCall,
+    cancel: &CancellationToken,
+    nesting_depth: u8,
+    provider: Option<Arc<dyn LlmProvider>>,
+) -> Result<Value, String> {
+    let tool = registry
+        .get(&tc.name)
+        .ok_or_else(|| format!("tool not found: {}", tc.name))?;
 
     tool.validate_input(&tc.arguments)
         .map_err(|e| format!("validation failed: {}", e.message))?;
@@ -994,6 +1020,12 @@ fn summarize_tool_input(args: &Value) -> String {
 
 const TASK_CONTEXT_HEADER: &str = "# Task Context";
 
+/// Backstop timeout for tool-call approval. Approval is human-in-the-loop, so we
+/// wait patiently for the user; this only guards against a request that is
+/// abandoned entirely (never answered, never cancelled) holding the run open
+/// forever. On expiry the tool is denied.
+const TOOL_APPROVAL_TIMEOUT: Duration = Duration::from_secs(30 * 60);
+
 const TASK_EXTRACT_PROMPT: &str = "\
 From the conversation below, extract the user's task:
 
diff --git a/src/components/AiToolApprovalDialog.tsx b/src/components/AiToolApprovalDialog.tsx
index 53a840d..b745ff1 100644
--- a/src/components/AiToolApprovalDialog.tsx
+++ b/src/components/AiToolApprovalDialog.tsx
@@ -20,7 +20,7 @@ export function AiToolApprovalDialog({ request, onResolve }: AiToolApprovalDialo
     if (request) onResolve(request.approvalId, false);
   }, [request, onResolve]);
 
-  // 30s 自动 deny 由后端兜底；前端不响应 Escape 以避免误关行为不明
+  // 后端有 30 分钟兜底超时（到期自动 deny）；前端不响应 Escape 以避免误关行为不明
   useEffect(() => {
     if (!request) return;
     const handler = (e: KeyboardEvent) => {

From f37b28f28da124070695cbb763ae700f7803874e Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Fri, 3 Jul 2026 10:39:55 +0800
Subject: [PATCH 03/10] fix(context-guard): use message count instead of index
 to avoid snapshot drift

---
 src-tauri/src/llm/context_guard.rs | 38 +++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/src-tauri/src/llm/context_guard.rs b/src-tauri/src/llm/context_guard.rs
index 5db4957..23266ae 100644
--- a/src-tauri/src/llm/context_guard.rs
+++ b/src-tauri/src/llm/context_guard.rs
@@ -40,6 +40,7 @@ pub struct ContextGuard {
 pub struct PrecomputedSummary {
     pub summary_text: String,
     pub summarized_up_to: usize,
+    pub summarized_count: usize,
 }
 
 impl ContextGuard {
@@ -133,9 +134,12 @@ impl ContextGuard {
             .ok()
             .filter(|t| !t.trim().is_empty())?;
 
+        let summarized_count = removable_indices.len();
+
         Some(PrecomputedSummary {
             summary_text,
             summarized_up_to: tail_boundary,
+            summarized_count,
         })
     }
 
@@ -148,8 +152,9 @@ impl ContextGuard {
             return false;
         }
 
-        let removable_indices: Vec<usize> = (0..cached.summarized_up_to.min(messages.len()))
+        let removable_indices: Vec<usize> = (0..messages.len())
             .filter(|&i| messages[i].role != "system")
+            .take(cached.summarized_count)
             .collect();
 
         for &i in removable_indices.iter().rev() {
@@ -816,6 +821,7 @@ mod tests {
         let cached = PrecomputedSummary {
             summary_text: "User asked about X, tool returned Y.".to_string(),
             summarized_up_to: 5,
+            summarized_count: 4,
         };
         let mut msgs = vec![
             sys("system prompt"),     // 0: system, skipped
@@ -843,6 +849,7 @@ mod tests {
         let cached = PrecomputedSummary {
             summary_text: "summary".to_string(),
             summarized_up_to: 10,
+            summarized_count: 0,
         };
         // Only 5 messages — fewer than summarized_up_to
         let mut msgs = vec![
@@ -863,6 +870,7 @@ mod tests {
         let cached = PrecomputedSummary {
             summary_text: "conversation summary".to_string(),
             summarized_up_to: 4,
+            summarized_count: 2,
         };
         let mut msgs = vec![
             sys("core system prompt"),  // 0: system, preserved
@@ -882,4 +890,32 @@ mod tests {
         assert!(msgs.iter().any(|m| m.content == "extra system"));
         assert!(msgs.iter().any(|m| m.content.contains("conversation summary")));
     }
+
+    #[test]
+    fn cached_summary_immune_to_system_insertion_before_apply() {
+        let guard = ContextGuard::new(Some(4096));
+        let cached = PrecomputedSummary {
+            summary_text: "summary of q1/a1".to_string(),
+            summarized_up_to: 3,
+            summarized_count: 2,
+        };
+        let mut msgs = vec![
+            sys("system prompt"),
+            sys("# User Model"),
+            sys("# Task Context"),
+            user("q1"),
+            assistant("a1"),
+            user("q2"),
+            assistant("a2"),
+        ];
+        let applied = guard.apply_cached_summary(&mut msgs, &cached);
+        assert!(applied);
+        assert!(!msgs.iter().any(|m| m.content == "q1"));
+        assert!(!msgs.iter().any(|m| m.content == "a1"));
+        assert!(msgs.iter().any(|m| m.content == "q2"));
+        assert!(msgs.iter().any(|m| m.content == "a2"));
+        assert!(msgs.iter().any(|m| m.content == "# User Model"));
+        assert!(msgs.iter().any(|m| m.content == "# Task Context"));
+        assert!(msgs.iter().any(|m| m.content.contains("summary of q1/a1")));
+    }
 }

From a6a2a1258fd643a65a1dc1656bb5e5539b05516b Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Fri, 3 Jul 2026 14:28:48 +0800
Subject: [PATCH 04/10] feat(planning): add structured plan step progress
 tracking

- Add plan.update_step tool for LLM to report step status
- Parse plan text into numbered steps in planning.rs
- Emit llm:plan-steps and llm:plan-step-update events
- Inject step-tracking instructions into Phase B prompt
- Add PlanStepInfo type and planSteps to ChatMessage.meta
- Frontend: plan-steps/plan-step-update event listeners
- Frontend: tree view rendering with step status indicators
- Frontend: tool calls nested under active plan step
- Detect plan.update_step in agent loop, emit step updates
- Graceful degradation: falls back to flat display if model
  doesn't call plan.update_step
---
 src-tauri/src/llm/agent_loop.rs               |  16 ++
 src-tauri/src/llm/planning.rs                 |  76 ++++++-
 src-tauri/src/tools/built_in/mod.rs           |   1 +
 src-tauri/src/tools/built_in/plan_step_ops.rs |  75 +++++++
 src-tauri/src/tools/mod.rs                    |  11 +-
 src/components/AiConversationPanel.css        |  74 +++++++
 src/components/AiConversationPanel.tsx        | 201 ++++++++++++++++--
 src/hooks/useWorkspaceAiConversations.ts      |   8 +
 8 files changed, 434 insertions(+), 28 deletions(-)
 create mode 100644 src-tauri/src/tools/built_in/plan_step_ops.rs

diff --git a/src-tauri/src/llm/agent_loop.rs b/src-tauri/src/llm/agent_loop.rs
index 708db27..2a83d5c 100644
--- a/src-tauri/src/llm/agent_loop.rs
+++ b/src-tauri/src/llm/agent_loop.rs
@@ -465,6 +465,15 @@ pub async fn run_agent_stream(
                 );
                 let error_message = result.as_ref().err().map(|e| e.as_str());
                 emit_tool_call_done(&app, &session_id, &tc.id, success, &result_summary, *duration_ms, error_message);
+
+                if tc.name == "plan.update_step" && success {
+                    if let (Some(step), Some(status)) = (
+                        tc.arguments.get("step").and_then(|v| v.as_u64()).map(|v| v as u32),
+                        tc.arguments.get("status").and_then(|v| v.as_str()),
+                    ) {
+                        emit_plan_step_update(&app, &session_id, step, status);
+                    }
+                }
             }
         }
 
@@ -965,6 +974,13 @@ fn emit_agent_done(app: &AppHandle, session_id: &str) {
     );
 }
 
+fn emit_plan_step_update(app: &AppHandle, session_id: &str, step: u32, status: &str) {
+    let _ = app.emit(
+        "llm:plan-step-update",
+        json!({ "sessionId": session_id, "step": step, "status": status }),
+    );
+}
+
 /// Truncate a string to `max_len` bytes, appending "..." if truncated.
 /// Respects Unicode character boundaries.
 fn truncate_str(s: &str, max_len: usize) -> String {
diff --git a/src-tauri/src/llm/planning.rs b/src-tauri/src/llm/planning.rs
index 8e65648..eb7d4a3 100644
--- a/src-tauri/src/llm/planning.rs
+++ b/src-tauri/src/llm/planning.rs
@@ -53,7 +53,9 @@ fn inject_plan_into_messages(
     out.push(LlmChatMessage {
         role: "system".to_string(),
         content: format!(
-            "Execute the following plan step by step. Call the tools listed. \
+            "Execute the following plan step by step. \
+             Before starting each step, call plan.update_step with {{\"step\": N, \"status\": \"in_progress\"}}. \
+             After completing each step, call plan.update_step with {{\"step\": N, \"status\": \"done\"}}. \
              After all steps, provide the final answer to the user.\n\n\
              Plan:\n{plan_text}"
         ),
@@ -62,6 +64,39 @@ fn inject_plan_into_messages(
     out
 }
 
+#[derive(Debug, Clone, serde::Serialize)]
+pub(crate) struct PlanStep {
+    pub step: u32,
+    pub title: String,
+}
+
+fn parse_plan_steps(plan_text: &str) -> Vec<PlanStep> {
+    plan_text
+        .lines()
+        .filter_map(|line| {
+            let trimmed = line.trim_start();
+            let dot_pos = trimmed.find(". ")?;
+            let num_part = &trimmed[..dot_pos];
+            if !num_part.chars().all(|c| c.is_ascii_digit()) || num_part.is_empty() {
+                return None;
+            }
+            let step = num_part.parse::<u32>().ok()?;
+            let title = trimmed[dot_pos + 2..].trim().to_string();
+            if title.is_empty() {
+                return None;
+            }
+            Some(PlanStep { step, title })
+        })
+        .collect()
+}
+
+fn emit_plan_steps(app: &AppHandle, session_id: &str, steps: &[PlanStep]) {
+    let _ = app.emit(
+        "llm:plan-steps",
+        json!({ "sessionId": session_id, "steps": steps }),
+    );
+}
+
 fn build_tool_descriptions(tools_json: &[Value]) -> String {
     let mut desc = String::new();
     for t in tools_json {
@@ -235,6 +270,10 @@ pub async fn run_planned_agent(
         );
     }
     let exec_messages = if plan_text.trim().len() >= MIN_PLAN_LENGTH {
+        let steps = parse_plan_steps(&plan_text);
+        if !steps.is_empty() {
+            emit_plan_steps(&app, &session_id, &steps);
+        }
         inject_plan_into_messages(&initial_messages, &plan_text)
     } else {
         initial_messages
@@ -289,9 +328,44 @@ mod tests {
         let result = inject_plan_into_messages(&msgs, plan);
         assert_eq!(result.len(), 2);
         assert!(result[1].content.contains("Execute the following plan"));
+        assert!(result[1].content.contains("plan.update_step"));
         assert!(result[1].content.contains("note.list"));
     }
 
+    #[test]
+    fn parse_plan_steps_numbered_list() {
+        let plan = "1. Search for notes about quantum physics\n2. Read the most relevant note\n3. Summarize findings";
+        let steps = parse_plan_steps(plan);
+        assert_eq!(steps.len(), 3);
+        assert_eq!(steps[0].step, 1);
+        assert_eq!(steps[0].title, "Search for notes about quantum physics");
+        assert_eq!(steps[2].step, 3);
+        assert_eq!(steps[2].title, "Summarize findings");
+    }
+
+    #[test]
+    fn parse_plan_steps_with_sub_items() {
+        let plan = "1. Search vault\n   - use keyword search\n   - filter by tag\n2. Read results";
+        let steps = parse_plan_steps(plan);
+        assert_eq!(steps.len(), 2);
+        assert_eq!(steps[0].step, 1);
+        assert_eq!(steps[1].step, 2);
+    }
+
+    #[test]
+    fn parse_plan_steps_empty_and_prose() {
+        assert!(parse_plan_steps("").is_empty());
+        assert!(parse_plan_steps("Just do whatever seems right").is_empty());
+    }
+
+    #[test]
+    fn parse_plan_steps_non_sequential() {
+        let plan = "1. First\n3. Third\n5. Fifth";
+        let steps = parse_plan_steps(plan);
+        assert_eq!(steps.len(), 3);
+        assert_eq!(steps[1].step, 3);
+    }
+
     #[test]
     fn build_tool_descriptions_extracts_names() {
         let tools = vec![
diff --git a/src-tauri/src/tools/built_in/mod.rs b/src-tauri/src/tools/built_in/mod.rs
index 93c158c..ea0061e 100644
--- a/src-tauri/src/tools/built_in/mod.rs
+++ b/src-tauri/src/tools/built_in/mod.rs
@@ -10,3 +10,4 @@ pub mod memory_ops;
 pub mod web_search;
 pub mod webview_renderer;
 pub mod tool_result_recall;
+pub mod plan_step_ops;
diff --git a/src-tauri/src/tools/built_in/plan_step_ops.rs b/src-tauri/src/tools/built_in/plan_step_ops.rs
new file mode 100644
index 0000000..c6326e1
--- /dev/null
+++ b/src-tauri/src/tools/built_in/plan_step_ops.rs
@@ -0,0 +1,75 @@
+use std::sync::Arc;
+
+use crate::tools::types::*;
+use crate::tools::context::ToolContext;
+
+pub struct PlanUpdateStepTool {
+    manifest: ToolManifest,
+}
+
+impl PlanUpdateStepTool {
+    pub fn new() -> Arc<Self> {
+        Arc::new(Self {
+            manifest: ToolManifest {
+                name: "plan.update_step".to_string(),
+                version: "1.0.0".to_string(),
+                protocol_version: "1.0".to_string(),
+                description: "Report progress during plan execution. Call before starting each step (status: in_progress) and after completing it (status: done).".to_string(),
+                input_schema: serde_json::json!({
+                    "type": "object",
+                    "properties": {
+                        "step": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "The step number from the plan"
+                        },
+                        "status": {
+                            "type": "string",
+                            "enum": ["in_progress", "done"],
+                            "description": "The step status"
+                        }
+                    },
+                    "required": ["step", "status"],
+                    "additionalProperties": false
+                }),
+                output_schema: serde_json::json!({
+                    "type": "object",
+                    "properties": {
+                        "ok": { "type": "boolean" }
+                    }
+                }),
+                effects: vec![],
+                risk: Risk::Safe,
+                privacy_aware: false,
+                requires_workspace: false,
+                default_approval: ApprovalPolicy::Auto,
+                examples: vec![],
+                tags: vec!["planning".to_string(), "utility".to_string()],
+                deprecated: None,
+            },
+        })
+    }
+}
+
+#[async_trait::async_trait]
+impl Tool for PlanUpdateStepTool {
+    fn manifest(&self) -> &ToolManifest {
+        &self.manifest
+    }
+
+    fn category(&self) -> ToolCategory {
+        ToolCategory::Utility
+    }
+
+    async fn invoke(&self, _ctx: &ToolContext, _input: serde_json::Value) -> ToolResult {
+        ToolResult::Ok {
+            data: serde_json::json!({ "ok": true }),
+            redacted_count: 0,
+            warnings: vec![],
+            metrics: ToolMetrics {
+                duration_ms: 0,
+                ..Default::default()
+            },
+        }
+    }
+}
diff --git a/src-tauri/src/tools/mod.rs b/src-tauri/src/tools/mod.rs
index ae2995d..58812c0 100644
--- a/src-tauri/src/tools/mod.rs
+++ b/src-tauri/src/tools/mod.rs
@@ -121,6 +121,9 @@ pub fn register_builtin_tools(
     // Tool result recall
     registry.register(Arc::new(built_in::tool_result_recall::ToolResultRecallTool::new()))?;
 
+    // Planning progress
+    registry.register(built_in::plan_step_ops::PlanUpdateStepTool::new())?;
+
     Ok(())
 }
 
@@ -140,9 +143,9 @@ mod mod_tests {
             "register_builtin_tools failed: {:?}",
             result.err()
         );
-        // 确认工具总数：1(time.now) + 9(P1) + 4(P3 写操作) + 2(memory) + 4(P4 网络) + 1(recall) = 21
+        // 确认工具总数：1(time.now) + 9(P1) + 4(P3 写操作) + 2(memory) + 4(P4 网络) + 1(recall) + 1(plan) = 22
         let tools = registry.list_for_llm(crate::tools::registry::ToolScope::Global);
-        assert_eq!(tools.len(), 21, "expected 21 registered tools, got {}", tools.len());
+        assert_eq!(tools.len(), 22, "expected 22 registered tools, got {}", tools.len());
     }
 
     #[test]
@@ -152,8 +155,8 @@ mod mod_tests {
         let all = registry.list_for_llm(crate::tools::registry::ToolScope::Global);
         let core = registry.list_for_llm_filtered(&crate::tools::registry::ToolFilter::core());
         assert!(core.len() < all.len(), "core ({}) should be less than all ({})", core.len(), all.len());
-        // NoteRead(6) + Utility(1 time.now + 2 memory + 1 recall) = 10
-        assert_eq!(core.len(), 10, "core should have 10 tools (6 NoteRead + 4 Utility)");
+        // NoteRead(6) + Utility(1 time.now + 2 memory + 1 recall + 1 plan) = 11
+        assert_eq!(core.len(), 11, "core should have 11 tools (6 NoteRead + 5 Utility)");
     }
 
     #[test]
diff --git a/src/components/AiConversationPanel.css b/src/components/AiConversationPanel.css
index 94a9c7d..6045551 100644
--- a/src/components/AiConversationPanel.css
+++ b/src/components/AiConversationPanel.css
@@ -306,3 +306,77 @@
   color: var(--fg-muted, #888);
   user-select: none;
 }
+
+/* Plan progress tree view */
+.ai-chat__plan-progress {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-bottom: 8px;
+}
+
+.ai-chat__plan-step {
+  border: 1px solid var(--border-subtle, #e0e0e0);
+  border-radius: 6px;
+  overflow: hidden;
+}
+
+.ai-chat__plan-step__header {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 10px;
+  cursor: pointer;
+  user-select: none;
+  font-size: 0.9em;
+  line-height: 1.4;
+}
+
+.ai-chat__plan-step__header::-webkit-details-marker {
+  display: none;
+}
+
+.ai-chat__plan-step__icon {
+  flex-shrink: 0;
+  width: 16px;
+  text-align: center;
+  font-size: 12px;
+}
+
+.ai-chat__plan-step__number {
+  flex-shrink: 0;
+  font-weight: 600;
+  color: var(--fg-muted, #888);
+  font-size: 0.85em;
+}
+
+.ai-chat__plan-step__title {
+  flex: 1;
+  min-width: 0;
+}
+
+.ai-chat__plan-step__tools {
+  margin: 0 8px 6px;
+  padding-left: 22px;
+}
+
+.ai-chat__plan-step--pending {
+  opacity: 0.6;
+}
+
+.ai-chat__plan-step--in_progress {
+  border-color: color-mix(in srgb, var(--kf-accent, #3b82f6) 60%, transparent);
+}
+
+.ai-chat__plan-step--in_progress .ai-chat__plan-step__icon {
+  color: var(--kf-accent, #3b82f6);
+  animation: ai-chat-tool-call-pulse 1.2s ease-in-out infinite;
+}
+
+.ai-chat__plan-step--done {
+  border-color: color-mix(in srgb, #16a34a 40%, transparent);
+}
+
+.ai-chat__plan-step--done .ai-chat__plan-step__icon {
+  color: #16a34a;
+}
diff --git a/src/components/AiConversationPanel.tsx b/src/components/AiConversationPanel.tsx
index b66b57d..f300dec 100644
--- a/src/components/AiConversationPanel.tsx
+++ b/src/components/AiConversationPanel.tsx
@@ -5,7 +5,7 @@ import { useTranslation } from "react-i18next";
 import { useAiConversationSession } from "../contexts/AiConversationSessionContext";
 import type { ThoughtFocusContext } from "../types/aiConversation";
 import { useAiNoteContext } from "../contexts/AiNoteContext";
-import type { ChatMessage, ToolCallDisplayInfo } from "../hooks/useWorkspaceAiConversations";
+import type { ChatMessage, PlanStepInfo, ToolCallDisplayInfo } from "../hooks/useWorkspaceAiConversations";
 import type { ReplyContextSources } from "../types/replyContextSources";
 import { hasReplyContextSourcesToShow } from "../types/replyContextSources";
 import type {
@@ -321,6 +321,8 @@ export function AiConversationPanel() {
   /** 映射：skillSessionId → { parentToolCallId } */
   const skillSessionMapRef = useRef<Map<string, { parentToolCallId: string }>>(new Map());
 
+  const activeStepRef = useRef<number | null>(null);
+
   /** Iter 5 #3：内置 skill manifest 缓存。skill 在后端 setup() 注册一次后不变，挂载时取一次即可。 */
   const [skillsCache, setSkillsCache] = useState<SkillManifestJson[]>([]);
   useEffect(() => {
@@ -968,11 +970,23 @@ export function AiConversationPanel() {
             });
             return;
           }
-          // 主会话的工具调用 → 添加到末尾 assistant 气泡的 toolCalls
+          if (p.toolName === "plan.update_step") return;
+          const currentStep = activeStepRef.current;
           setMessages((prev) => {
             const next = [...prev];
             const last = next[next.length - 1];
             if (last?.role !== "assistant") return prev;
+            if (currentStep != null && last.meta?.planSteps) {
+              const steps = last.meta.planSteps.map((s) =>
+                s.step === currentStep
+                  ? { ...s, toolCalls: [...s.toolCalls, newCall] }
+                  : s,
+              );
+              return [
+                ...next.slice(0, -1),
+                { ...last, meta: { ...last.meta, planSteps: steps } },
+              ];
+            }
             const existing = last.meta?.toolCalls ?? [];
             return [
               ...next.slice(0, -1),
@@ -1019,32 +1033,33 @@ export function AiConversationPanel() {
             });
             return;
           }
-          // 主会话的工具完成 → 从后向前搜索 toolCallId
           setMessages((prev) => {
-            let foundIndex = -1;
+            const patchTc = (tc: ToolCallDisplayInfo): ToolCallDisplayInfo =>
+              tc.toolCallId === p.toolCallId
+                ? { ...tc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
+                : tc;
+
             for (let i = prev.length - 1; i >= 0; i -= 1) {
               const m = prev[i];
               if (m.role !== "assistant") continue;
+
+              if (m.meta?.planSteps?.some((s) => s.toolCalls.some((tc) => tc.toolCallId === p.toolCallId))) {
+                const steps = m.meta.planSteps.map((s) => ({
+                  ...s,
+                  toolCalls: s.toolCalls.map(patchTc),
+                }));
+                const next = [...prev];
+                next[i] = { ...m, meta: { ...m.meta, planSteps: steps } };
+                return next;
+              }
+
               if (m.meta?.toolCalls?.some((tc) => tc.toolCallId === p.toolCallId)) {
-                foundIndex = i;
-                break;
+                const next = [...prev];
+                next[i] = { ...m, meta: { ...m.meta, toolCalls: m.meta.toolCalls!.map(patchTc) } };
+                return next;
               }
             }
-            if (foundIndex === -1) {
-              return prev;
-            }
-            const target = prev[foundIndex];
-            const updatedCalls = (target.meta?.toolCalls ?? []).map((tc) =>
-              tc.toolCallId === p.toolCallId
-                ? { ...tc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
-                : tc,
-            );
-            const next = [...prev];
-            next[foundIndex] = {
-              ...target,
-              meta: { ...target.meta, toolCalls: updatedCalls },
-            };
-            return next;
+            return prev;
           });
         },
       ),
@@ -1153,6 +1168,49 @@ export function AiConversationPanel() {
           });
         }
       }),
+      listen<{ sessionId: string; steps: { step: number; title: string }[] }>("llm:plan-steps", (e) => {
+        if (e.payload.sessionId !== activeSessionRef.current) return;
+        activeStepRef.current = null;
+        const planSteps: PlanStepInfo[] = e.payload.steps.map((s) => ({
+          step: s.step,
+          title: s.title,
+          status: "pending" as const,
+          toolCalls: [],
+        }));
+        setMessages((prev) => {
+          const next = [...prev];
+          const last = next[next.length - 1];
+          if (last?.role === "assistant") {
+            next[next.length - 1] = {
+              ...last,
+              meta: { ...last.meta, planSteps },
+            };
+          }
+          return next;
+        });
+      }),
+      listen<{ sessionId: string; step: number; status: string }>("llm:plan-step-update", (e) => {
+        if (e.payload.sessionId !== activeSessionRef.current) return;
+        const { step, status } = e.payload;
+        if (status === "in_progress") {
+          activeStepRef.current = step;
+        }
+        setMessages((prev) => {
+          const next = [...prev];
+          for (let i = next.length - 1; i >= 0; i--) {
+            const m = next[i];
+            if (m.role !== "assistant" || !m.meta?.planSteps) continue;
+            const steps = m.meta.planSteps.map((s) =>
+              s.step === step
+                ? { ...s, status: status as PlanStepInfo["status"] }
+                : s,
+            );
+            next[i] = { ...m, meta: { ...m.meta, planSteps: steps } };
+            break;
+          }
+          return next;
+        });
+      }),
       // Budget warning: tool call budget reaching 80%
       listen<{ sessionId: string; used: number; limit: number; type: string }>(
         "llm:budget-warning",
@@ -1260,6 +1318,7 @@ export function AiConversationPanel() {
         markNeedPersist();
         activeSessionRef.current = null;
         isAgentModeRef.current = false;
+        activeStepRef.current = null;
         setIsStreaming(false);
         setIsVaultSearching(false);
         setIsPlanning(false);
@@ -2200,7 +2259,103 @@ export function AiConversationPanel() {
               <div className={`ai-chat__bubble ai-chat__bubble--${m.role}`}>
                 {m.role === "assistant" ? (
                   <>
-                    {m.meta?.toolCalls && m.meta.toolCalls.length > 0 ? (
+                    {m.meta?.planSteps && m.meta.planSteps.length > 0 ? (
+                      <div className="ai-chat__plan-progress">
+                        {m.meta.planSteps.map((ps) => (
+                          <details
+                            key={ps.step}
+                            className={`ai-chat__plan-step ai-chat__plan-step--${ps.status}`}
+                            open={ps.status === "in_progress"}
+                          >
+                            <summary className="ai-chat__plan-step__header">
+                              <span className="ai-chat__plan-step__icon" aria-hidden={true}>
+                                {ps.status === "done" ? "✓" : ps.status === "in_progress" ? "⋯" : "○"}
+                              </span>
+                              <span className="ai-chat__plan-step__number">{ps.step}.</span>
+                              <span className="ai-chat__plan-step__title">{ps.title}</span>
+                            </summary>
+                            {ps.toolCalls.length > 0 && (
+                              <div className="ai-chat__tool-calls ai-chat__plan-step__tools">
+                                {ps.toolCalls.map((tc) => (
+                                  <details key={tc.toolCallId} className="ai-chat__tool-call-details">
+                                    <summary className={`ai-chat__tool-call ai-chat__tool-call--${tc.status}`}>
+                                      <span className="ai-chat__tool-call__icon" aria-hidden={true}>
+                                        {tc.status === "running" ? "⋯" : tc.status === "done" ? "✓" : "✗"}
+                                      </span>
+                                      <span className="ai-chat__tool-call__name">{tc.toolName}</span>
+                                      {tc.durationMs != null && (
+                                        <span className="ai-chat__tool-call__duration">
+                                          {(tc.durationMs / 1000).toFixed(1)}s
+                                        </span>
+                                      )}
+                                    </summary>
+                                    <div className="ai-chat__tool-call__detail">
+                                      {tc.inputSummary && (
+                                        <div className="ai-chat__tool-call__input">
+                                          <span className="ai-chat__tool-call__label">输入</span>
+                                          <code>{tc.inputSummary}</code>
+                                        </div>
+                                      )}
+                                      {tc.resultSummary && (
+                                        <div className="ai-chat__tool-call__result">
+                                          <span className="ai-chat__tool-call__label">结果</span>
+                                          <code>{tc.resultSummary}</code>
+                                        </div>
+                                      )}
+                                      {tc.errorMessage && (
+                                        <div className="ai-chat__tool-call__error">
+                                          <span className="ai-chat__tool-call__label">错误</span>
+                                          <code>{tc.errorMessage}</code>
+                                        </div>
+                                      )}
+                                    </div>
+                                  </details>
+                                ))}
+                              </div>
+                            )}
+                          </details>
+                        ))}
+                        {m.meta.toolCalls && m.meta.toolCalls.length > 0 ? (
+                          <div className="ai-chat__tool-calls">
+                            {m.meta.toolCalls.map((tc) => (
+                              <details key={tc.toolCallId} className="ai-chat__tool-call-details">
+                                <summary className={`ai-chat__tool-call ai-chat__tool-call--${tc.status}`}>
+                                  <span className="ai-chat__tool-call__icon" aria-hidden={true}>
+                                    {tc.status === "running" ? "⋯" : tc.status === "done" ? "✓" : "✗"}
+                                  </span>
+                                  <span className="ai-chat__tool-call__name">{tc.toolName}</span>
+                                  {tc.durationMs != null && (
+                                    <span className="ai-chat__tool-call__duration">
+                                      {(tc.durationMs / 1000).toFixed(1)}s
+                                    </span>
+                                  )}
+                                </summary>
+                                <div className="ai-chat__tool-call__detail">
+                                  {tc.inputSummary && (
+                                    <div className="ai-chat__tool-call__input">
+                                      <span className="ai-chat__tool-call__label">输入</span>
+                                      <code>{tc.inputSummary}</code>
+                                    </div>
+                                  )}
+                                  {tc.resultSummary && (
+                                    <div className="ai-chat__tool-call__result">
+                                      <span className="ai-chat__tool-call__label">结果</span>
+                                      <code>{tc.resultSummary}</code>
+                                    </div>
+                                  )}
+                                  {tc.errorMessage && (
+                                    <div className="ai-chat__tool-call__error">
+                                      <span className="ai-chat__tool-call__label">错误</span>
+                                      <code>{tc.errorMessage}</code>
+                                    </div>
+                                  )}
+                                </div>
+                              </details>
+                            ))}
+                          </div>
+                        ) : null}
+                      </div>
+                    ) : m.meta?.toolCalls && m.meta.toolCalls.length > 0 ? (
                       <div className="ai-chat__tool-calls">
                         {m.meta.toolCalls.map((tc) => (
                           <details key={tc.toolCallId} className="ai-chat__tool-call-details">
@@ -2290,7 +2445,7 @@ export function AiConversationPanel() {
                         Agent {m.meta.budgetWarning.used}/{m.meta.budgetWarning.limit} tool calls used
                       </div>
                     )}
-                    {m.meta?.planningText && (
+                    {!m.meta?.planSteps && m.meta?.planningText && (
                       <details className="ai-chat__planning-fold">
                         <summary>Plan</summary>
                         <AiAssistantMarkdown content={m.meta.planningText} />
diff --git a/src/hooks/useWorkspaceAiConversations.ts b/src/hooks/useWorkspaceAiConversations.ts
index 1f8fe9b..247c2a1 100644
--- a/src/hooks/useWorkspaceAiConversations.ts
+++ b/src/hooks/useWorkspaceAiConversations.ts
@@ -36,6 +36,13 @@ export type ToolCallDisplayInfo = {
   skillStreaming?: boolean;
 };
 
+export type PlanStepInfo = {
+  step: number;
+  title: string;
+  status: "pending" | "in_progress" | "done";
+  toolCalls: ToolCallDisplayInfo[];
+};
+
 export type ChatMessage = {
   id: string;
   role: "user" | "assistant";
@@ -62,6 +69,7 @@ export type ChatMessage = {
     skillId?: string;
     skillName?: string;
     planningText?: string;
+    planSteps?: PlanStepInfo[];
   };
 };
 

From 63186e51de0facb70cbc26ec32d7cd149b28df42 Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Fri, 3 Jul 2026 16:49:02 +0800
Subject: [PATCH 05/10] refactor(planning): simplify to single-phase execution

Remove plan approval gate and merge Phase A/B into a
single agent_loop call. Planning mode now only adds a
system prompt; no separate plan generation or step
tracking.

Co-authored-by: Claude (Opus 4.6) <noreply@anthropic.com>
---
 src-tauri/src/ai_conversations.rs             |  11 +
 src-tauri/src/lib.rs                          |   2 -
 src-tauri/src/llm/agent_loop.rs               |  58 ++-
 src-tauri/src/llm/mod.rs                      |  27 --
 src-tauri/src/llm/plan_approval.rs            | 149 ------
 src-tauri/src/llm/planning.rs                 | 354 +-------------
 src-tauri/src/tools/built_in/mod.rs           |   1 -
 src-tauri/src/tools/built_in/plan_step_ops.rs |  75 ---
 src-tauri/src/tools/mod.rs                    |  11 +-
 src-tauri/src/vault_config.rs                 |  18 -
 src/components/AiConversationPanel.css        |  90 ----
 src/components/AiConversationPanel.tsx        | 444 +++---------------
 src/components/AiLlmSettingsModal.tsx         |  28 --
 src/components/AiPlanApprovalDialog.css       | 156 ------
 src/components/AiPlanApprovalDialog.tsx       |  73 ---
 src/hooks/useWorkspaceAiConversations.ts      |  54 ++-
 src/locales/en.json                           |   6 -
 src/locales/zh.json                           |   6 -
 src/types/aiConversation.ts                   |  16 +
 src/types/toolTypes.ts                        |  11 -
 src/types/vaultAiConfig.ts                    |   2 -
 src/utils/toolInvoke.ts                       |  13 -
 22 files changed, 194 insertions(+), 1411 deletions(-)
 delete mode 100644 src-tauri/src/llm/plan_approval.rs
 delete mode 100644 src-tauri/src/tools/built_in/plan_step_ops.rs
 delete mode 100644 src/components/AiPlanApprovalDialog.css
 delete mode 100644 src/components/AiPlanApprovalDialog.tsx

diff --git a/src-tauri/src/ai_conversations.rs b/src-tauri/src/ai_conversations.rs
index 41e3f1d..7dbfcd5 100644
--- a/src-tauri/src/ai_conversations.rs
+++ b/src-tauri/src/ai_conversations.rs
@@ -122,6 +122,8 @@ struct PersistedMessageDisk {
     skill_id: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     skill_name: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    tool_calls: Option<Value>,
 }
 
 /// 会话级「想法聚焦」上下文（磁盘与 LLM 字段对齐）
@@ -249,6 +251,8 @@ pub struct PersistedMessageOut {
     pub skill_id: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub skill_name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_calls: Option<Value>,
 }
 
 #[derive(Debug, Clone, Serialize)]
@@ -299,6 +303,8 @@ pub struct PersistedMessageIn {
     pub skill_id: Option<String>,
     #[serde(default)]
     pub skill_name: Option<String>,
+    #[serde(default)]
+    pub tool_calls: Option<Value>,
 }
 
 #[derive(Debug, Clone, Deserialize)]
@@ -358,6 +364,7 @@ fn validate_messages_for_save(msgs: &[PersistedMessageIn]) -> Result<Vec<Persist
             reply_context_sources: m.reply_context_sources.clone(),
             skill_id: m.skill_id.clone(),
             skill_name: m.skill_name.clone(),
+            tool_calls: m.tool_calls.clone(),
         });
     }
     Ok(out)
@@ -473,6 +480,7 @@ fn load_ai_conversation_for_subdir(root: &Path, subdir: &str, args: LoadAiConver
             reply_context_sources: m.reply_context_sources,
             skill_id: m.skill_id,
             skill_name: m.skill_name,
+            tool_calls: m.tool_calls,
         })
         .collect();
     Ok(ConversationBodyOut {
@@ -642,6 +650,7 @@ mod tests {
                         reply_context_sources: None,
                         skill_id: None,
                         skill_name: None,
+                        tool_calls: None,
                     },
                     PersistedMessageIn {
                         id: "a1".to_string(),
@@ -651,6 +660,7 @@ mod tests {
                         reply_context_sources: None,
                         skill_id: None,
                         skill_name: None,
+                        tool_calls: None,
                     },
                 ],
                 set_as_active: Some(true),
@@ -680,6 +690,7 @@ mod tests {
             reply_context_sources: None,
             skill_id: None,
             skill_name: None,
+            tool_calls: None,
         }];
         assert_eq!(compute_title_from_messages(&msgs), "New chat");
     }
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 293e949..7c4712f 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -1712,7 +1712,6 @@ pub fn run() {
         .manage(Arc::new(semantic_index::EmbeddingCache::new()))
         .manage(Arc::new(llm::LlmSessionState::default()))
         .manage(Arc::new(llm::approval::ToolApprovalState::new()))
-        .manage(Arc::new(llm::plan_approval::PlanApprovalState::new()))
         .manage(Arc::new(tools::ToolRegistry::new()))
         .manage(Arc::new(skills::SkillRegistry::new()))
         .manage(Arc::new(tokio::sync::Semaphore::new(skills::SKILL_CONCURRENCY)))
@@ -1748,7 +1747,6 @@ pub fn run() {
             llm::start_chat_stream,
             llm::abort_llm_stream,
             llm::respond_tool_approval,
-            llm::respond_plan_approval,
             llm::clear_conversation_approvals,
             list_ai_conversations,
             create_ai_conversation,
diff --git a/src-tauri/src/llm/agent_loop.rs b/src-tauri/src/llm/agent_loop.rs
index 2a83d5c..665bb36 100644
--- a/src-tauri/src/llm/agent_loop.rs
+++ b/src-tauri/src/llm/agent_loop.rs
@@ -371,7 +371,8 @@ pub async fn run_agent_stream(
         // 4. NormalizedToolCall already carries an ID (UUID v7 or server-provided)
         for tc in &normalized_calls {
             let input_summary = summarize_tool_input(&tc.arguments);
-            emit_tool_call_start(&app, &session_id, &tc.id, &tc.name, &input_summary);
+            let display_summary = generate_tool_display_summary(&tc.name, &tc.arguments);
+            emit_tool_call_start(&app, &session_id, &tc.id, &tc.name, &input_summary, &display_summary);
         }
 
         // 5. 并行执行工具（跳过循环调用；每个工具有独立超时，支持取消）
@@ -466,14 +467,7 @@ pub async fn run_agent_stream(
                 let error_message = result.as_ref().err().map(|e| e.as_str());
                 emit_tool_call_done(&app, &session_id, &tc.id, success, &result_summary, *duration_ms, error_message);
 
-                if tc.name == "plan.update_step" && success {
-                    if let (Some(step), Some(status)) = (
-                        tc.arguments.get("step").and_then(|v| v.as_u64()).map(|v| v as u32),
-                        tc.arguments.get("status").and_then(|v| v.as_str()),
-                    ) {
-                        emit_plan_step_update(&app, &session_id, step, status);
-                    }
-                }
+
             }
         }
 
@@ -941,7 +935,7 @@ pub fn list_for_llm_to_tools(manifests: &[Value]) -> Vec<Value> {
         .collect()
 }
 
-fn emit_tool_call_start(app: &AppHandle, session_id: &str, tool_call_id: &str, tool_name: &str, input_summary: &str) {
+fn emit_tool_call_start(app: &AppHandle, session_id: &str, tool_call_id: &str, tool_name: &str, input_summary: &str, display_summary: &str) {
     let _ = app.emit(
         "llm:tool-call-start",
         json!({
@@ -949,10 +943,47 @@ fn emit_tool_call_start(app: &AppHandle, session_id: &str, tool_call_id: &str, t
             "toolCallId": tool_call_id,
             "toolName": tool_name,
             "inputSummary": input_summary,
+            "displaySummary": display_summary,
         }),
     );
 }
 
+fn generate_tool_display_summary(name: &str, args: &Value) -> String {
+    let get_str = |key: &str| args.get(key).and_then(|v| v.as_str()).unwrap_or("");
+
+    match name {
+        "note.list" => "List notes".into(),
+        "note.read" => format!("Read {}", truncate_str(get_str("rel_path"), 40)),
+        "note.create" => format!("Create {}", truncate_str(get_str("rel_path"), 40)),
+        "note.append" => format!("Append to {}", truncate_str(get_str("rel_path"), 40)),
+        "note.write_section" => format!("Edit {}", truncate_str(get_str("rel_path"), 40)),
+
+        "vault.search_keyword" => format!("Search: {}", truncate_str(get_str("query"), 40)),
+        "vault.semantic_search" => format!("Semantic search: {}", truncate_str(get_str("query"), 40)),
+
+        "web.search" => format!("Web search: {}", truncate_str(get_str("query"), 40)),
+        "web.read_page" => format!("Read page: {}", truncate_str(get_str("url"), 50)),
+        "web.read_pdf" => format!("Read PDF: {}", truncate_str(get_str("url"), 50)),
+        "web.download" => format!("Download: {}", truncate_str(get_str("url"), 50)),
+
+        "thought.list" => "List thoughts".into(),
+        "thought.read" => format!("Read thought {}", truncate_str(get_str("thought_id"), 20)),
+        "thought.create" => "Create thought".into(),
+
+        "graph.query_topic_network" => format!("Query graph: {}", truncate_str(get_str("topic"), 30)),
+        "link.suggest_related" => "Suggest related links".into(),
+
+        "memory.save" => format!("Save memory: {}", truncate_str(get_str("category"), 20)),
+        "memory.forget" => "Forget memory".into(),
+
+        "tool.recall" => format!("Recall: {}", truncate_str(get_str("tool_call_id"), 20)),
+
+        n if n.starts_with("skill.") => format!("Skill: {}", &n[6..]),
+
+        _ => name.to_string(),
+    }
+}
+
 fn emit_tool_call_done(app: &AppHandle, session_id: &str, tool_call_id: &str, success: bool, result_summary: &str, duration_ms: u64, error_message: Option<&str>) {
     let _ = app.emit(
         "llm:tool-call-done",
@@ -974,13 +1005,6 @@ fn emit_agent_done(app: &AppHandle, session_id: &str) {
     );
 }
 
-fn emit_plan_step_update(app: &AppHandle, session_id: &str, step: u32, status: &str) {
-    let _ = app.emit(
-        "llm:plan-step-update",
-        json!({ "sessionId": session_id, "step": step, "status": status }),
-    );
-}
-
 /// Truncate a string to `max_len` bytes, appending "..." if truncated.
 /// Respects Unicode character boundaries.
 fn truncate_str(s: &str, max_len: usize) -> String {
diff --git a/src-tauri/src/llm/mod.rs b/src-tauri/src/llm/mod.rs
index 4d8b41d..2fd4d27 100644
--- a/src-tauri/src/llm/mod.rs
+++ b/src-tauri/src/llm/mod.rs
@@ -2,7 +2,6 @@
 
 pub(crate) mod agent_loop;
 pub mod approval;
-pub mod plan_approval;
 pub(crate) mod context_guard;
 pub(crate) mod planning;
 pub(crate) mod provider;
@@ -810,7 +809,6 @@ pub async fn start_chat_stream(
     registry: State<'_, Arc<ToolRegistry>>,
     ctx_factory: State<'_, Arc<ToolContextFactory>>,
     approval: State<'_, Arc<approval::ToolApprovalState>>,
-    plan_approval: State<'_, Arc<plan_approval::PlanApprovalState>>,
     skills: State<'_, Arc<SkillRegistry>>,
     http_client: State<'_, Arc<reqwest::Client>>,
     embed_cache_state: State<'_, Arc<semantic_index::EmbeddingCache>>,
@@ -884,7 +882,6 @@ pub async fn start_chat_stream(
     let registry_arc = Arc::clone(registry.inner());
     let ctx_factory_arc = Arc::clone(ctx_factory.inner());
     let approval_arc = Arc::clone(approval.inner());
-    let plan_approval_arc = Arc::clone(plan_approval.inner());
     let workspace_root = root.clone();
     let conversation_id = args
         .conversation_id
@@ -1042,8 +1039,6 @@ pub async fn start_chat_stream(
                         loop_config,
                         conversation_id,
                         approval_arc,
-                        plan_approval_arc,
-                        ai.planning_approval_enabled,
                         memory_manager.clone(),
                     )
                     .await;
@@ -1244,28 +1239,6 @@ pub fn respond_tool_approval(
     approval.resolve(&args.approval_id, args.decision)
 }
 
-#[derive(Debug, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct RespondPlanApprovalArgs {
-    pub approval_id: String,
-    /// "approve" | "reject"
-    pub decision: String,
-}
-
-/// 前端响应一次计划审批请求（执行 / 拒绝）。
-#[tauri::command]
-pub fn respond_plan_approval(
-    args: RespondPlanApprovalArgs,
-    plan_approval: State<'_, Arc<plan_approval::PlanApprovalState>>,
-) -> Result<(), String> {
-    let decision = match args.decision.as_str() {
-        "approve" => plan_approval::PlanDecision::Approve,
-        "reject" => plan_approval::PlanDecision::Reject,
-        other => return Err(format!("unknown plan approval decision: {other}")),
-    };
-    plan_approval.resolve(&args.approval_id, decision)
-}
-
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ClearConversationApprovalsArgs {
diff --git a/src-tauri/src/llm/plan_approval.rs b/src-tauri/src/llm/plan_approval.rs
deleted file mode 100644
index 409aef6..0000000
--- a/src-tauri/src/llm/plan_approval.rs
+++ /dev/null
@@ -1,149 +0,0 @@
-//! 计划审批状态（Phase A→B 之间的门控）。
-//!
-//! `run_planned_agent` 在 Phase A 生成计划后调用 [`PlanApprovalState::register`] 拿到
-//! receiver + [`PlanApprovalPendingGuard`]，emit `llm:plan-approval-request`，然后
-//! `tokio::time::timeout` + `tokio::select!` 等待。guard 在外层 cancel 导致 future 被 drop 时
-//! 自动 `discard_pending`，防止 sender 泄漏在 map 中。计划审批每次都问，不做会话级缓存。
-//!
-//! 仅提供"执行 / 拒绝"两态：计划是提示词的派生预览，不可编辑——用户若不认可应拒绝并
-//! 修改提示词重发，保持"提示词是唯一意图来源"，避免与目标稳定性等机制产生冲突。
-
-use std::collections::HashMap;
-use std::sync::{Arc, Mutex};
-
-use tokio::sync::oneshot;
-
-/// 前端对一次计划审批请求的决策。
-pub enum PlanDecision {
-    /// 按计划执行。
-    Approve,
-    /// 拒绝执行，丢弃整个请求。
-    Reject,
-}
-
-pub struct PlanApprovalState {
-    pending: Mutex<HashMap<String, oneshot::Sender<PlanDecision>>>,
-}
-
-/// RAII 守卫：drop 时清理 pending 条目，避免外层 cancel 把 sender 留在 map 里。
-/// `discard_pending` 对不存在的 id 是 no-op，所以 happy path（resolve 已 remove）也安全。
-pub struct PlanApprovalPendingGuard {
-    state: Arc<PlanApprovalState>,
-    approval_id: String,
-}
-
-impl Drop for PlanApprovalPendingGuard {
-    fn drop(&mut self) {
-        self.state.discard_pending(&self.approval_id);
-    }
-}
-
-impl Default for PlanApprovalState {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl PlanApprovalState {
-    pub fn new() -> Self {
-        Self {
-            pending: Mutex::new(HashMap::new()),
-        }
-    }
-
-    /// 登记一个 pending 审批，返回 (approval_id, receiver, guard)。
-    /// approval_id 用 UUID v4 生成，无序无关联以防泄漏其他元信息。
-    /// guard 需由调用方持有直到 await 结束。
-    pub fn register(
-        self: &Arc<Self>,
-    ) -> (String, oneshot::Receiver<PlanDecision>, PlanApprovalPendingGuard) {
-        let approval_id = uuid::Uuid::new_v4().to_string();
-        let (tx, rx) = oneshot::channel();
-        {
-            let mut g = match self.pending.lock() {
-                Ok(g) => g,
-                Err(p) => p.into_inner(),
-            };
-            g.insert(approval_id.clone(), tx);
-        }
-        let guard = PlanApprovalPendingGuard {
-            state: self.clone(),
-            approval_id: approval_id.clone(),
-        };
-        (approval_id, rx, guard)
-    }
-
-    /// 前端响应：取出 sender 并 send。若 id 不存在或 receiver 已 drop，返回 Err。
-    pub fn resolve(&self, approval_id: &str, decision: PlanDecision) -> Result<(), String> {
-        let tx = {
-            let mut g = match self.pending.lock() {
-                Ok(g) => g,
-                Err(p) => p.into_inner(),
-            };
-            g.remove(approval_id)
-                .ok_or_else(|| format!("unknown approval_id: {approval_id}"))?
-        };
-        tx.send(decision)
-            .map_err(|_| "approval receiver dropped (timed out or cancelled)".to_string())
-    }
-
-    /// 超时或取消时清理 pending 项（receiver 已 drop，sender 留在 map 里会泄漏）。
-    pub fn discard_pending(&self, approval_id: &str) {
-        let mut g = match self.pending.lock() {
-            Ok(g) => g,
-            Err(p) => p.into_inner(),
-        };
-        g.remove(approval_id);
-    }
-
-    #[cfg(test)]
-    fn pending_len(&self) -> usize {
-        let g = match self.pending.lock() {
-            Ok(g) => g,
-            Err(p) => p.into_inner(),
-        };
-        g.len()
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[tokio::test]
-    async fn register_then_resolve_delivers_approve() {
-        let state = Arc::new(PlanApprovalState::new());
-        let (id, rx, _guard) = state.register();
-        state.resolve(&id, PlanDecision::Approve).unwrap();
-        assert!(matches!(rx.await.unwrap(), PlanDecision::Approve));
-    }
-
-    #[tokio::test]
-    async fn resolve_delivers_reject() {
-        let state = Arc::new(PlanApprovalState::new());
-        let (id, rx, _guard) = state.register();
-        state.resolve(&id, PlanDecision::Reject).unwrap();
-        assert!(matches!(rx.await.unwrap(), PlanDecision::Reject));
-    }
-
-    #[tokio::test]
-    async fn resolve_unknown_id_errors() {
-        let state = PlanApprovalState::new();
-        let err = state.resolve("nope", PlanDecision::Approve).unwrap_err();
-        assert!(err.contains("unknown"));
-    }
-
-    #[tokio::test]
-    async fn guard_drop_cleans_pending_and_resolve_fails() {
-        let state = Arc::new(PlanApprovalState::new());
-        assert_eq!(state.pending_len(), 0);
-        let id = {
-            let (id, _rx, _guard) = state.register();
-            assert_eq!(state.pending_len(), 1);
-            id
-        };
-        assert_eq!(state.pending_len(), 0);
-        let err = state.resolve(&id, PlanDecision::Approve).unwrap_err();
-        assert!(err.contains("unknown"));
-    }
-}
diff --git a/src-tauri/src/llm/planning.rs b/src-tauri/src/llm/planning.rs
index eb7d4a3..0444d23 100644
--- a/src-tauri/src/llm/planning.rs
+++ b/src-tauri/src/llm/planning.rs
@@ -1,196 +1,26 @@
 use std::path::PathBuf;
 use std::sync::Arc;
-use std::time::Duration;
 
-use serde_json::{json, Value};
-use tauri::{AppHandle, Emitter};
+use serde_json::Value;
 use tokio_util::sync::CancellationToken;
 
 use super::agent_loop::{self, AgentLoopConfig, SharedMemoryManager};
 use super::approval::ToolApprovalState;
-use super::plan_approval::{PlanApprovalState, PlanDecision};
 use super::provider::LlmProvider;
 use super::LlmChatMessage;
 use crate::tools::context::ToolContextFactory;
 use crate::tools::registry::ToolRegistry;
-
-/// How long to wait for the user to act on a plan-approval request before
-/// degrading to auto-execution. Longer than the per-tool approval timeout
-/// (120s) since reviewing/editing a full plan takes more time.
-const PLAN_APPROVAL_TIMEOUT: Duration = Duration::from_secs(300);
+use tauri::AppHandle;
 
 const PLANNING_SYSTEM_PROMPT: &str = "\
-Analyze the user's request carefully. Output a numbered plan listing the exact tool calls \
-you would make and why. Do NOT call any tools — only output the plan as plain text.\n\n\
-Available tools:\n";
-
-const MIN_PLAN_LENGTH: usize = 10;
-
-fn build_planning_messages(
-    messages: &[LlmChatMessage],
-    tool_descriptions: &str,
-) -> Vec<LlmChatMessage> {
-    let mut out = Vec::with_capacity(messages.len() + 1);
-    for m in messages {
-        out.push(m.clone());
-    }
-    out.push(LlmChatMessage {
-        role: "system".to_string(),
-        content: format!("{PLANNING_SYSTEM_PROMPT}{tool_descriptions}"),
-        ..Default::default()
-    });
-    out
-}
-
-fn inject_plan_into_messages(
-    messages: &[LlmChatMessage],
-    plan_text: &str,
-) -> Vec<LlmChatMessage> {
-    let mut out = Vec::with_capacity(messages.len() + 1);
-    for m in messages {
-        out.push(m.clone());
-    }
-    out.push(LlmChatMessage {
-        role: "system".to_string(),
-        content: format!(
-            "Execute the following plan step by step. \
-             Before starting each step, call plan.update_step with {{\"step\": N, \"status\": \"in_progress\"}}. \
-             After completing each step, call plan.update_step with {{\"step\": N, \"status\": \"done\"}}. \
-             After all steps, provide the final answer to the user.\n\n\
-             Plan:\n{plan_text}"
-        ),
-        ..Default::default()
-    });
-    out
-}
-
-#[derive(Debug, Clone, serde::Serialize)]
-pub(crate) struct PlanStep {
-    pub step: u32,
-    pub title: String,
-}
-
-fn parse_plan_steps(plan_text: &str) -> Vec<PlanStep> {
-    plan_text
-        .lines()
-        .filter_map(|line| {
-            let trimmed = line.trim_start();
-            let dot_pos = trimmed.find(". ")?;
-            let num_part = &trimmed[..dot_pos];
-            if !num_part.chars().all(|c| c.is_ascii_digit()) || num_part.is_empty() {
-                return None;
-            }
-            let step = num_part.parse::<u32>().ok()?;
-            let title = trimmed[dot_pos + 2..].trim().to_string();
-            if title.is_empty() {
-                return None;
-            }
-            Some(PlanStep { step, title })
-        })
-        .collect()
-}
-
-fn emit_plan_steps(app: &AppHandle, session_id: &str, steps: &[PlanStep]) {
-    let _ = app.emit(
-        "llm:plan-steps",
-        json!({ "sessionId": session_id, "steps": steps }),
-    );
-}
-
-fn build_tool_descriptions(tools_json: &[Value]) -> String {
-    let mut desc = String::new();
-    for t in tools_json {
-        let name = t
-            .pointer("/function/name")
-            .and_then(|v| v.as_str())
-            .unwrap_or("?");
-        let description = t
-            .pointer("/function/description")
-            .and_then(|v| v.as_str())
-            .unwrap_or("");
-        desc.push_str(&format!("- {name}: {description}\n"));
-    }
-    desc
-}
-
-pub(crate) fn emit_planning_start(app: &AppHandle, session_id: &str) {
-    let _ = app.emit(
-        "llm:planning-start",
-        json!({ "sessionId": session_id }),
-    );
-}
-
-pub(crate) fn emit_planning_done(app: &AppHandle, session_id: &str, plan_text: &str) {
-    let _ = app.emit(
-        "llm:planning-done",
-        json!({ "sessionId": session_id, "planText": plan_text }),
-    );
-}
-
-/// Emit `llm:agent-done` when we short-circuit before the agent loop runs
-/// (e.g. the user rejected the plan), so the frontend clears its streaming state.
-fn emit_agent_done(app: &AppHandle, session_id: &str) {
-    let _ = app.emit("llm:agent-done", json!({ "sessionId": session_id }));
-}
-
-/// Emit when the approval gate concludes by ANY means (approve / reject / timeout /
-/// cancel), so the frontend dismisses the approval card. Interactive resolutions
-/// (button clicks) also clear it optimistically on the frontend; this covers the
-/// non-interactive paths (timeout auto-execute, cancel) where no click happens.
-fn emit_plan_approval_resolved(app: &AppHandle, session_id: &str) {
-    let _ = app.emit("llm:plan-approval-resolved", json!({ "sessionId": session_id }));
-}
-
-/// Outcome of the plan-approval gate between Phase A and Phase B.
-enum PlanGateOutcome {
-    /// Proceed to execution with the original plan.
-    Proceed,
-    /// User rejected the plan; abandon the request.
-    Reject,
-    /// Cancelled while waiting.
-    Cancelled,
-}
-
-/// Emit `llm:plan-approval-request` and wait for the user's decision.
-/// Timeout or a closed channel degrades to executing the plan —
-/// rejecting on timeout would silently drop the whole user request.
-async fn wait_for_plan_approval(
-    app: &AppHandle,
-    session_id: &str,
-    conversation_id: &str,
-    state: &Arc<PlanApprovalState>,
-    plan_text: &str,
-    cancel: &CancellationToken,
-) -> PlanGateOutcome {
-    let (approval_id, rx, _guard) = state.register();
-    let _ = app.emit(
-        "llm:plan-approval-request",
-        json!({
-            "sessionId": session_id,
-            "conversationId": conversation_id,
-            "approvalId": approval_id,
-            "planText": plan_text,
-        }),
-    );
-
-    let decision = tokio::select! {
-        res = tokio::time::timeout(PLAN_APPROVAL_TIMEOUT, rx) => res,
-        _ = cancel.cancelled() => return PlanGateOutcome::Cancelled,
-    };
-
-    match decision {
-        Ok(Ok(PlanDecision::Approve)) => PlanGateOutcome::Proceed,
-        Ok(Ok(PlanDecision::Reject)) => PlanGateOutcome::Reject,
-        // Elapsed (Err) or sender dropped (Ok(Err)): degrade to auto-execute.
-        Ok(Err(_)) | Err(_) => PlanGateOutcome::Proceed,
-    }
-}
+Before making any tool calls, briefly explain your approach in 1-2 sentences.\n\
+Then proceed to execute step by step.";
 
 #[allow(clippy::too_many_arguments)]
 pub async fn run_planned_agent(
     app: AppHandle,
     session_id: String,
-    initial_messages: Vec<LlmChatMessage>,
+    mut initial_messages: Vec<LlmChatMessage>,
     tools_json: Vec<Value>,
     registry: Arc<ToolRegistry>,
     ctx_factory: Arc<ToolContextFactory>,
@@ -202,87 +32,18 @@ pub async fn run_planned_agent(
     config: AgentLoopConfig,
     conversation_id: String,
     approval_state: Arc<ToolApprovalState>,
-    plan_approval_state: Arc<PlanApprovalState>,
-    planning_approval_enabled: bool,
     memory_manager: SharedMemoryManager,
 ) -> String {
-    // Phase A: Planning (no tools, text-only output)
-    let tool_desc = build_tool_descriptions(&tools_json);
-    let plan_messages = build_planning_messages(&initial_messages, &tool_desc);
-
-    emit_planning_start(&app, &session_id);
-
-    let plan_result = provider
-        .chat_stream(
-            &app,
-            &session_id,
-            plan_messages,
-            None,
-            cancel.clone(),
-        )
-        .await;
-
-    let plan_text = match plan_result {
-        Ok(r) => r.content,
-        Err(_) => String::new(),
-    };
-
-    emit_planning_done(&app, &session_id, &plan_text);
-
-    if cancel.is_cancelled() {
-        return String::new();
-    }
-
-    // Plan-approval gate (between Phase A and Phase B). Skipped when disabled or
-    // when there is no real plan to review (too short → Phase A likely failed).
-    if planning_approval_enabled && plan_text.trim().len() >= MIN_PLAN_LENGTH {
-        let outcome = wait_for_plan_approval(
-            &app,
-            &session_id,
-            &conversation_id,
-            &plan_approval_state,
-            &plan_text,
-            &cancel,
-        )
-        .await;
-
-        // Dismiss the approval card no matter how the gate resolved — including
-        // timeout/cancel, where the user never clicked and the frontend would
-        // otherwise leave the card up covering the execution output.
-        emit_plan_approval_resolved(&app, &session_id);
-
-        match outcome {
-            PlanGateOutcome::Proceed => {}
-            PlanGateOutcome::Reject => {
-                emit_agent_done(&app, &session_id);
-                return String::new();
-            }
-            PlanGateOutcome::Cancelled => return String::new(),
-        }
-    }
-
-    // Phase B: Execution (inject plan, normal agent loop)
-    if std::env::var("KNOWFORGE_DEBUG_PLANNING").is_ok() {
-        eprintln!(
-            "[planning] Phase B plan_text ({} chars):\n{}\n[planning] --- end plan ---",
-            plan_text.trim().len(),
-            plan_text.trim()
-        );
-    }
-    let exec_messages = if plan_text.trim().len() >= MIN_PLAN_LENGTH {
-        let steps = parse_plan_steps(&plan_text);
-        if !steps.is_empty() {
-            emit_plan_steps(&app, &session_id, &steps);
-        }
-        inject_plan_into_messages(&initial_messages, &plan_text)
-    } else {
-        initial_messages
-    };
+    initial_messages.push(LlmChatMessage {
+        role: "system".to_string(),
+        content: PLANNING_SYSTEM_PROMPT.to_string(),
+        ..Default::default()
+    });
 
     agent_loop::run_agent_stream(
         app,
         session_id,
-        exec_messages,
+        initial_messages,
         tools_json,
         registry,
         ctx_factory,
@@ -298,96 +59,3 @@ pub async fn run_planned_agent(
     )
     .await
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn build_planning_messages_appends_system() {
-        let msgs = vec![LlmChatMessage {
-            role: "user".to_string(),
-            content: "search my notes".to_string(),
-            ..Default::default()
-        }];
-        let result = build_planning_messages(&msgs, "- note.list: list notes\n");
-        assert_eq!(result.len(), 2);
-        assert_eq!(result[1].role, "system");
-        assert!(result[1].content.contains("note.list"));
-        assert!(result[1].content.contains("Do NOT call any tools"));
-    }
-
-    #[test]
-    fn inject_plan_adds_execution_guidance() {
-        let msgs = vec![LlmChatMessage {
-            role: "user".to_string(),
-            content: "find my notes".to_string(),
-            ..Default::default()
-        }];
-        let plan = "1. Call note.list\n2. Read top result";
-        let result = inject_plan_into_messages(&msgs, plan);
-        assert_eq!(result.len(), 2);
-        assert!(result[1].content.contains("Execute the following plan"));
-        assert!(result[1].content.contains("plan.update_step"));
-        assert!(result[1].content.contains("note.list"));
-    }
-
-    #[test]
-    fn parse_plan_steps_numbered_list() {
-        let plan = "1. Search for notes about quantum physics\n2. Read the most relevant note\n3. Summarize findings";
-        let steps = parse_plan_steps(plan);
-        assert_eq!(steps.len(), 3);
-        assert_eq!(steps[0].step, 1);
-        assert_eq!(steps[0].title, "Search for notes about quantum physics");
-        assert_eq!(steps[2].step, 3);
-        assert_eq!(steps[2].title, "Summarize findings");
-    }
-
-    #[test]
-    fn parse_plan_steps_with_sub_items() {
-        let plan = "1. Search vault\n   - use keyword search\n   - filter by tag\n2. Read results";
-        let steps = parse_plan_steps(plan);
-        assert_eq!(steps.len(), 2);
-        assert_eq!(steps[0].step, 1);
-        assert_eq!(steps[1].step, 2);
-    }
-
-    #[test]
-    fn parse_plan_steps_empty_and_prose() {
-        assert!(parse_plan_steps("").is_empty());
-        assert!(parse_plan_steps("Just do whatever seems right").is_empty());
-    }
-
-    #[test]
-    fn parse_plan_steps_non_sequential() {
-        let plan = "1. First\n3. Third\n5. Fifth";
-        let steps = parse_plan_steps(plan);
-        assert_eq!(steps.len(), 3);
-        assert_eq!(steps[1].step, 3);
-    }
-
-    #[test]
-    fn build_tool_descriptions_extracts_names() {
-        let tools = vec![
-            json!({
-                "type": "function",
-                "function": {
-                    "name": "note.list",
-                    "description": "List notes in the vault",
-                    "parameters": {}
-                }
-            }),
-            json!({
-                "type": "function",
-                "function": {
-                    "name": "web.search",
-                    "description": "Search the web",
-                    "parameters": {}
-                }
-            }),
-        ];
-        let desc = build_tool_descriptions(&tools);
-        assert!(desc.contains("- note.list: List notes in the vault"));
-        assert!(desc.contains("- web.search: Search the web"));
-    }
-}
diff --git a/src-tauri/src/tools/built_in/mod.rs b/src-tauri/src/tools/built_in/mod.rs
index ea0061e..93c158c 100644
--- a/src-tauri/src/tools/built_in/mod.rs
+++ b/src-tauri/src/tools/built_in/mod.rs
@@ -10,4 +10,3 @@ pub mod memory_ops;
 pub mod web_search;
 pub mod webview_renderer;
 pub mod tool_result_recall;
-pub mod plan_step_ops;
diff --git a/src-tauri/src/tools/built_in/plan_step_ops.rs b/src-tauri/src/tools/built_in/plan_step_ops.rs
deleted file mode 100644
index c6326e1..0000000
--- a/src-tauri/src/tools/built_in/plan_step_ops.rs
+++ /dev/null
@@ -1,75 +0,0 @@
-use std::sync::Arc;
-
-use crate::tools::types::*;
-use crate::tools::context::ToolContext;
-
-pub struct PlanUpdateStepTool {
-    manifest: ToolManifest,
-}
-
-impl PlanUpdateStepTool {
-    pub fn new() -> Arc<Self> {
-        Arc::new(Self {
-            manifest: ToolManifest {
-                name: "plan.update_step".to_string(),
-                version: "1.0.0".to_string(),
-                protocol_version: "1.0".to_string(),
-                description: "Report progress during plan execution. Call before starting each step (status: in_progress) and after completing it (status: done).".to_string(),
-                input_schema: serde_json::json!({
-                    "type": "object",
-                    "properties": {
-                        "step": {
-                            "type": "integer",
-                            "minimum": 1,
-                            "description": "The step number from the plan"
-                        },
-                        "status": {
-                            "type": "string",
-                            "enum": ["in_progress", "done"],
-                            "description": "The step status"
-                        }
-                    },
-                    "required": ["step", "status"],
-                    "additionalProperties": false
-                }),
-                output_schema: serde_json::json!({
-                    "type": "object",
-                    "properties": {
-                        "ok": { "type": "boolean" }
-                    }
-                }),
-                effects: vec![],
-                risk: Risk::Safe,
-                privacy_aware: false,
-                requires_workspace: false,
-                default_approval: ApprovalPolicy::Auto,
-                examples: vec![],
-                tags: vec!["planning".to_string(), "utility".to_string()],
-                deprecated: None,
-            },
-        })
-    }
-}
-
-#[async_trait::async_trait]
-impl Tool for PlanUpdateStepTool {
-    fn manifest(&self) -> &ToolManifest {
-        &self.manifest
-    }
-
-    fn category(&self) -> ToolCategory {
-        ToolCategory::Utility
-    }
-
-    async fn invoke(&self, _ctx: &ToolContext, _input: serde_json::Value) -> ToolResult {
-        ToolResult::Ok {
-            data: serde_json::json!({ "ok": true }),
-            redacted_count: 0,
-            warnings: vec![],
-            metrics: ToolMetrics {
-                duration_ms: 0,
-                ..Default::default()
-            },
-        }
-    }
-}
diff --git a/src-tauri/src/tools/mod.rs b/src-tauri/src/tools/mod.rs
index 58812c0..ae2995d 100644
--- a/src-tauri/src/tools/mod.rs
+++ b/src-tauri/src/tools/mod.rs
@@ -121,9 +121,6 @@ pub fn register_builtin_tools(
     // Tool result recall
     registry.register(Arc::new(built_in::tool_result_recall::ToolResultRecallTool::new()))?;
 
-    // Planning progress
-    registry.register(built_in::plan_step_ops::PlanUpdateStepTool::new())?;
-
     Ok(())
 }
 
@@ -143,9 +140,9 @@ mod mod_tests {
             "register_builtin_tools failed: {:?}",
             result.err()
         );
-        // 确认工具总数：1(time.now) + 9(P1) + 4(P3 写操作) + 2(memory) + 4(P4 网络) + 1(recall) + 1(plan) = 22
+        // 确认工具总数：1(time.now) + 9(P1) + 4(P3 写操作) + 2(memory) + 4(P4 网络) + 1(recall) = 21
         let tools = registry.list_for_llm(crate::tools::registry::ToolScope::Global);
-        assert_eq!(tools.len(), 22, "expected 22 registered tools, got {}", tools.len());
+        assert_eq!(tools.len(), 21, "expected 21 registered tools, got {}", tools.len());
     }
 
     #[test]
@@ -155,8 +152,8 @@ mod mod_tests {
         let all = registry.list_for_llm(crate::tools::registry::ToolScope::Global);
         let core = registry.list_for_llm_filtered(&crate::tools::registry::ToolFilter::core());
         assert!(core.len() < all.len(), "core ({}) should be less than all ({})", core.len(), all.len());
-        // NoteRead(6) + Utility(1 time.now + 2 memory + 1 recall + 1 plan) = 11
-        assert_eq!(core.len(), 11, "core should have 11 tools (6 NoteRead + 5 Utility)");
+        // NoteRead(6) + Utility(1 time.now + 2 memory + 1 recall) = 10
+        assert_eq!(core.len(), 10, "core should have 10 tools (6 NoteRead + 4 Utility)");
     }
 
     #[test]
diff --git a/src-tauri/src/vault_config.rs b/src-tauri/src/vault_config.rs
index 619190a..5536002 100644
--- a/src-tauri/src/vault_config.rs
+++ b/src-tauri/src/vault_config.rs
@@ -223,11 +223,6 @@ pub struct AiConfig {
     pub tools_enabled: bool,
     #[serde(default)]
     pub planning_enabled: bool,
-    /// Gate the plan-approval step between Phase A (plan) and Phase B (execute).
-    /// Defaults to true so planning users review plans before execution; only
-    /// takes effect when `planning_enabled` is true.
-    #[serde(default = "default_planning_approval_enabled")]
-    pub planning_approval_enabled: bool,
     #[serde(default = "default_memory_enabled")]
     pub memory_enabled: bool,
     #[serde(default = "default_memory_reflection_mode")]
@@ -260,10 +255,6 @@ fn default_tools_enabled() -> bool {
     true
 }
 
-fn default_planning_approval_enabled() -> bool {
-    true
-}
-
 fn default_memory_enabled() -> bool {
     true
 }
@@ -285,7 +276,6 @@ impl Default for AiConfig {
             privacy: AiPrivacy::default(),
             tools_enabled: true,
             planning_enabled: false,
-            planning_approval_enabled: true,
             memory_enabled: true,
             memory_reflection_mode: default_memory_reflection_mode(),
         }
@@ -522,7 +512,6 @@ struct AiDiskPartial {
     privacy: Option<AiPrivacyPartial>,
     tools_enabled: Option<bool>,
     planning_enabled: Option<bool>,
-    planning_approval_enabled: Option<bool>,
     memory_enabled: Option<bool>,
     memory_reflection_mode: Option<String>,
 }
@@ -680,7 +669,6 @@ pub struct AiConfigPatch {
     pub privacy: Option<AiPrivacyPatch>,
     pub tools_enabled: Option<bool>,
     pub planning_enabled: Option<bool>,
-    pub planning_approval_enabled: Option<bool>,
     pub memory_enabled: Option<bool>,
     pub memory_reflection_mode: Option<String>,
 }
@@ -816,7 +804,6 @@ pub struct AiConfigForUi {
     pub privacy: AiPrivacy,
     pub tools_enabled: bool,
     pub planning_enabled: bool,
-    pub planning_approval_enabled: bool,
     pub memory_enabled: bool,
     pub memory_reflection_mode: String,
 }
@@ -963,9 +950,6 @@ fn merge_ai_from_disk_partial(mut cfg: AiConfig, partial: AiDiskPartial) -> AiCo
     if let Some(v) = partial.planning_enabled {
         cfg.planning_enabled = v;
     }
-    if let Some(v) = partial.planning_approval_enabled {
-        cfg.planning_approval_enabled = v;
-    }
     if let Some(v) = partial.memory_enabled {
         cfg.memory_enabled = v;
     }
@@ -1042,7 +1026,6 @@ fn to_ai_for_ui(ai: AiConfig) -> AiConfigForUi {
         privacy: ai.privacy,
         tools_enabled: ai.tools_enabled,
         planning_enabled: ai.planning_enabled,
-        planning_approval_enabled: ai.planning_approval_enabled,
         memory_enabled: ai.memory_enabled,
         memory_reflection_mode: ai.memory_reflection_mode,
     }
@@ -1316,7 +1299,6 @@ fn apply_ai_patch(cfg: &mut AiConfig, patch: AiConfigPatch) {
     }
     if let Some(v) = patch.tools_enabled { cfg.tools_enabled = v; }
     if let Some(v) = patch.planning_enabled { cfg.planning_enabled = v; }
-    if let Some(v) = patch.planning_approval_enabled { cfg.planning_approval_enabled = v; }
     if let Some(v) = patch.memory_enabled { cfg.memory_enabled = v; }
     if let Some(v) = patch.memory_reflection_mode { cfg.memory_reflection_mode = v; }
 }
diff --git a/src/components/AiConversationPanel.css b/src/components/AiConversationPanel.css
index 6045551..6f3d58b 100644
--- a/src/components/AiConversationPanel.css
+++ b/src/components/AiConversationPanel.css
@@ -290,93 +290,3 @@
   }
 }
 
-/* Planning phase: live streaming + fold */
-.ai-chat__planning-live {
-  opacity: 0.5;
-}
-.ai-chat__planning-fold {
-  margin-bottom: 0.5em;
-  border: 1px solid var(--border-subtle, #e0e0e0);
-  border-radius: 4px;
-  padding: 2px 8px;
-  font-size: 0.9em;
-}
-.ai-chat__planning-fold summary {
-  cursor: pointer;
-  color: var(--fg-muted, #888);
-  user-select: none;
-}
-
-/* Plan progress tree view */
-.ai-chat__plan-progress {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  margin-bottom: 8px;
-}
-
-.ai-chat__plan-step {
-  border: 1px solid var(--border-subtle, #e0e0e0);
-  border-radius: 6px;
-  overflow: hidden;
-}
-
-.ai-chat__plan-step__header {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 6px 10px;
-  cursor: pointer;
-  user-select: none;
-  font-size: 0.9em;
-  line-height: 1.4;
-}
-
-.ai-chat__plan-step__header::-webkit-details-marker {
-  display: none;
-}
-
-.ai-chat__plan-step__icon {
-  flex-shrink: 0;
-  width: 16px;
-  text-align: center;
-  font-size: 12px;
-}
-
-.ai-chat__plan-step__number {
-  flex-shrink: 0;
-  font-weight: 600;
-  color: var(--fg-muted, #888);
-  font-size: 0.85em;
-}
-
-.ai-chat__plan-step__title {
-  flex: 1;
-  min-width: 0;
-}
-
-.ai-chat__plan-step__tools {
-  margin: 0 8px 6px;
-  padding-left: 22px;
-}
-
-.ai-chat__plan-step--pending {
-  opacity: 0.6;
-}
-
-.ai-chat__plan-step--in_progress {
-  border-color: color-mix(in srgb, var(--kf-accent, #3b82f6) 60%, transparent);
-}
-
-.ai-chat__plan-step--in_progress .ai-chat__plan-step__icon {
-  color: var(--kf-accent, #3b82f6);
-  animation: ai-chat-tool-call-pulse 1.2s ease-in-out infinite;
-}
-
-.ai-chat__plan-step--done {
-  border-color: color-mix(in srgb, #16a34a 40%, transparent);
-}
-
-.ai-chat__plan-step--done .ai-chat__plan-step__icon {
-  color: #16a34a;
-}
diff --git a/src/components/AiConversationPanel.tsx b/src/components/AiConversationPanel.tsx
index f300dec..f06ab63 100644
--- a/src/components/AiConversationPanel.tsx
+++ b/src/components/AiConversationPanel.tsx
@@ -5,7 +5,7 @@ import { useTranslation } from "react-i18next";
 import { useAiConversationSession } from "../contexts/AiConversationSessionContext";
 import type { ThoughtFocusContext } from "../types/aiConversation";
 import { useAiNoteContext } from "../contexts/AiNoteContext";
-import type { ChatMessage, PlanStepInfo, ToolCallDisplayInfo } from "../hooks/useWorkspaceAiConversations";
+import type { ChatMessage, ToolCallDisplayInfo } from "../hooks/useWorkspaceAiConversations";
 import type { ReplyContextSources } from "../types/replyContextSources";
 import { hasReplyContextSourcesToShow } from "../types/replyContextSources";
 import type {
@@ -21,9 +21,8 @@ import { VAULT_CONFIG_UPDATED_EVENT } from "../utils/vaultConfigBroadcast";
 import { markdownTreatAsKfPrivateForUi } from "../utils/kfPrivateMarkdown";
 import { PrivacyChangeOverlay } from "./PrivacyChangeOverlay";
 import { AiToolApprovalDialog } from "./AiToolApprovalDialog";
-import { AiPlanApprovalDialog } from "./AiPlanApprovalDialog";
-import type { ApprovalRequest, PlanApprovalRequest } from "../types/toolTypes";
-import { respondPlanApproval, respondToolApproval } from "../utils/toolInvoke";
+import type { ApprovalRequest } from "../types/toolTypes";
+import { respondToolApproval } from "../utils/toolInvoke";
 import { listSkills, invokeSkill } from "../utils/skillInvoke";
 import type { SkillManifestJson } from "../types/skillTypes";
 import { parseSlashCommand } from "../utils/parseSlashCommand";
@@ -81,6 +80,35 @@ function finalizeStreamingAssistant(prev: ChatMessage[]): ChatMessage[] {
   return next;
 }
 
+/**
+ * Search for a ToolCallDisplayInfo by toolCallId in flat toolCalls.
+ * When found, apply the patcher and return the updated messages array.
+ * Returns null if not found.
+ */
+function findAndPatchToolCall(
+  prev: ChatMessage[],
+  targetToolCallId: string,
+  patcher: (tc: ToolCallDisplayInfo) => ToolCallDisplayInfo,
+): ChatMessage[] | null {
+  for (let i = prev.length - 1; i >= 0; i--) {
+    const m = prev[i];
+    if (m.role !== "assistant") continue;
+
+    const tcs = m.meta?.toolCalls;
+    if (tcs) {
+      const tcIdx = tcs.findIndex((tc) => tc.toolCallId === targetToolCallId);
+      if (tcIdx !== -1) {
+        const next = [...prev];
+        const updated = [...tcs];
+        updated[tcIdx] = patcher(updated[tcIdx]);
+        next[i] = { ...m, meta: { ...m.meta, toolCalls: updated } };
+        return next;
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * 合并流式增量，兼容重复监听或上游偶发返回「全量片段」导致的重复拼接。
  * - `delta` 与当前尾部完全重复：忽略；
@@ -301,7 +329,7 @@ export function AiConversationPanel() {
   const [copyToast, setCopyToast] = useState<"copied" | "failed" | null>(null);
   const [privacyHint, setPrivacyHint] = useState<string | null>(null);
   const [vaultSearchSummary, setVaultSearchSummary] = useState<string | null>(null);
-  const [isPlanning, setIsPlanning] = useState(false);
+
 
   const activeSessionRef = useRef<string | null>(null);
   const listEndRef = useRef<HTMLDivElement>(null);
@@ -321,8 +349,6 @@ export function AiConversationPanel() {
   /** 映射：skillSessionId → { parentToolCallId } */
   const skillSessionMapRef = useRef<Map<string, { parentToolCallId: string }>>(new Map());
 
-  const activeStepRef = useRef<number | null>(null);
-
   /** Iter 5 #3：内置 skill manifest 缓存。skill 在后端 setup() 注册一次后不变，挂载时取一次即可。 */
   const [skillsCache, setSkillsCache] = useState<SkillManifestJson[]>([]);
   useEffect(() => {
@@ -422,38 +448,6 @@ export function AiConversationPanel() {
     setActiveApproval(null);
   }, [conversationId]);
 
-  /** 计划审批：Planning 模式每个 run 只有一份计划，无需队列 */
-  const [activePlanApproval, setActivePlanApproval] =
-    useState<PlanApprovalRequest | null>(null);
-  const handlePlanApprove = useCallback((approvalId: string) => {
-    void respondPlanApproval(approvalId, "approve").catch(() => {});
-    setActivePlanApproval(null);
-  }, []);
-  const handlePlanReject = useCallback((approvalId: string) => {
-    void respondPlanApproval(approvalId, "reject").catch(() => {});
-    setActivePlanApproval(null);
-    // 拒绝后把触发本次的提示词回填到输入框，方便用户修改后重发
-    // （提示词是唯一意图来源，改提示词而非改计划）。
-    setMessages((prev) => {
-      for (let i = prev.length - 1; i >= 0; i--) {
-        if (prev[i].role === "user") {
-          const lastUser = prev[i].content;
-          if (lastUser.length > 0) {
-            queueMicrotask(() => {
-              setInput(lastUser);
-              composerRef.current?.focus();
-            });
-          }
-          break;
-        }
-      }
-      return prev;
-    });
-  }, []);
-  useEffect(() => {
-    setActivePlanApproval(null);
-  }, [conversationId]);
-
   /** invite-after-answer 状态 */
   const [inviteData, setInviteData] = useState<InviteData | null>(null);
   const [challengeInlineData, setChallengeInlineData] = useState<ChallengeInlineData | null>(null);
@@ -646,29 +640,12 @@ export function AiConversationPanel() {
         }
         const skillMapping = skillSessionMapRef.current.get(p.sessionId);
         if (skillMapping) {
-          // Skill 会话的 chunk → 追加到父气泡的工具调用项的 skillContent
-          setMessages((prev) => {
-            const next = [...prev];
-            for (let i = next.length - 1; i >= 0; i--) {
-              const m = next[i];
-              if (m.role !== "assistant") continue;
-              const tcs = m.meta?.toolCalls;
-              if (!tcs) continue;
-              const tcIdx = tcs.findIndex((tc) => tc.toolCallId === skillMapping.parentToolCallId);
-              if (tcIdx === -1) continue;
-              const updatedCalls = [...tcs];
-              updatedCalls[tcIdx] = {
-                ...updatedCalls[tcIdx],
-                skillContent: (updatedCalls[tcIdx].skillContent || "") + p.delta,
-              };
-              next[i] = {
-                ...m,
-                meta: { ...m.meta, toolCalls: updatedCalls },
-              };
-              break;
-            }
-            return next;
-          });
+          setMessages((prev) =>
+            findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+              ...tc,
+              skillContent: (tc.skillContent || "") + p.delta,
+            })) ?? prev,
+          );
           return;
         }
         // 主会话的 chunk → 追加到气泡 content（原有逻辑）
@@ -930,7 +907,7 @@ export function AiConversationPanel() {
       }),
       // P2 Tool Calling Loop：工具调用开始 → 在末尾 assistant 消息中插入 running 状态项
       // Skill 内部的工具调用路由到对应 toolCall 的 skillToolCalls
-      listen<{ sessionId: string; toolCallId: string; toolName: string; inputSummary?: string }>(
+      listen<{ sessionId: string; toolCallId: string; toolName: string; inputSummary?: string; displaySummary?: string }>(
         "llm:tool-call-start",
         (e) => {
           const p = e.payload;
@@ -941,52 +918,23 @@ export function AiConversationPanel() {
           const newCall: ToolCallDisplayInfo = {
             toolCallId: p.toolCallId,
             toolName: p.toolName,
+            displaySummary: p.displaySummary || undefined,
             status: "running",
             inputSummary: p.inputSummary,
           };
           if (skillMapping) {
-            // Skill 内部的工具调用 → 添加到对应的 skillToolCalls
-            setMessages((prev) => {
-              const next = [...prev];
-              for (let i = next.length - 1; i >= 0; i--) {
-                const m = next[i];
-                if (m.role !== "assistant") continue;
-                const tcs = m.meta?.toolCalls;
-                if (!tcs) continue;
-                const tcIdx = tcs.findIndex((tc) => tc.toolCallId === skillMapping.parentToolCallId);
-                if (tcIdx === -1) continue;
-                const updatedCalls = [...tcs];
-                updatedCalls[tcIdx] = {
-                  ...updatedCalls[tcIdx],
-                  skillToolCalls: [...(updatedCalls[tcIdx].skillToolCalls || []), newCall],
-                };
-                next[i] = {
-                  ...m,
-                  meta: { ...m.meta, toolCalls: updatedCalls },
-                };
-                break;
-              }
-              return next;
-            });
+            setMessages((prev) =>
+              findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+                ...tc,
+                skillToolCalls: [...(tc.skillToolCalls || []), newCall],
+              })) ?? prev,
+            );
             return;
           }
-          if (p.toolName === "plan.update_step") return;
-          const currentStep = activeStepRef.current;
           setMessages((prev) => {
             const next = [...prev];
             const last = next[next.length - 1];
             if (last?.role !== "assistant") return prev;
-            if (currentStep != null && last.meta?.planSteps) {
-              const steps = last.meta.planSteps.map((s) =>
-                s.step === currentStep
-                  ? { ...s, toolCalls: [...s.toolCalls, newCall] }
-                  : s,
-              );
-              return [
-                ...next.slice(0, -1),
-                { ...last, meta: { ...last.meta, planSteps: steps } },
-              ];
-            }
             const existing = last.meta?.toolCalls ?? [];
             return [
               ...next.slice(0, -1),
@@ -1009,28 +957,16 @@ export function AiConversationPanel() {
           }
           const skillMapping = skillSessionMapRef.current.get(p.sessionId);
           if (skillMapping) {
-            // Skill 内部的工具完成 → 更新对应的 skillToolCalls
-            setMessages((prev) => {
-              const next = [...prev];
-              for (let i = next.length - 1; i >= 0; i--) {
-                const m = next[i];
-                if (m.role !== "assistant") continue;
-                const tcs = m.meta?.toolCalls;
-                if (!tcs) continue;
-                const tcIdx = tcs.findIndex((tc) => tc.toolCallId === skillMapping.parentToolCallId);
-                if (tcIdx === -1) continue;
-                const updatedCalls = [...tcs];
-                const skillTcs = (updatedCalls[tcIdx].skillToolCalls || []).map((stc) =>
+            setMessages((prev) =>
+              findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+                ...tc,
+                skillToolCalls: (tc.skillToolCalls || []).map((stc) =>
                   stc.toolCallId === p.toolCallId
                     ? { ...stc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
                     : stc,
-                );
-                updatedCalls[tcIdx] = { ...updatedCalls[tcIdx], skillToolCalls: skillTcs };
-                next[i] = { ...m, meta: { ...m.meta, toolCalls: updatedCalls } };
-                break;
-              }
-              return next;
-            });
+                ),
+              })) ?? prev,
+            );
             return;
           }
           setMessages((prev) => {
@@ -1043,16 +979,6 @@ export function AiConversationPanel() {
               const m = prev[i];
               if (m.role !== "assistant") continue;
 
-              if (m.meta?.planSteps?.some((s) => s.toolCalls.some((tc) => tc.toolCallId === p.toolCallId))) {
-                const steps = m.meta.planSteps.map((s) => ({
-                  ...s,
-                  toolCalls: s.toolCalls.map(patchTc),
-                }));
-                const next = [...prev];
-                next[i] = { ...m, meta: { ...m.meta, planSteps: steps } };
-                return next;
-              }
-
               if (m.meta?.toolCalls?.some((tc) => tc.toolCallId === p.toolCallId)) {
                 const next = [...prev];
                 next[i] = { ...m, meta: { ...m.meta, toolCalls: m.meta.toolCalls!.map(patchTc) } };
@@ -1106,110 +1032,16 @@ export function AiConversationPanel() {
         skillSessionMapRef.current.set(p.sessionId, {
           parentToolCallId: p.parentToolCallId,
         });
-        // 更新父气泡中对应工具调用项的 skill 字段（不创建新气泡）
-        setMessages((prev) => {
-          const next = [...prev];
-          for (let i = next.length - 1; i >= 0; i--) {
-            const m = next[i];
-            if (m.role !== "assistant") continue;
-            const tcs = m.meta?.toolCalls;
-            if (!tcs) continue;
-            const tcIdx = tcs.findIndex((tc) => tc.toolCallId === p.parentToolCallId);
-            if (tcIdx === -1) continue;
-            const updatedCalls = [...tcs];
-            updatedCalls[tcIdx] = {
-              ...updatedCalls[tcIdx],
-              skillId: p.skillId,
-              skillName: p.skillName,
-              skillContent: "",
-              skillToolCalls: [],
-              skillStreaming: true,
-            };
-            next[i] = {
-              ...m,
-              meta: { ...m.meta, toolCalls: updatedCalls },
-            };
-            break;
-          }
-          return next;
-        });
-      }),
-      listen<PlanApprovalRequest>("llm:plan-approval-request", (e) => {
-        if (e.payload.sessionId !== activeSessionRef.current) return;
-        setActivePlanApproval(e.payload);
-      }),
-      // Gate resolved by any means (approve/reject/timeout/cancel) — dismiss the
-      // card. Covers non-interactive paths (timeout auto-execute) where the user
-      // never clicked, so the card would otherwise linger over the output.
-      listen<{ sessionId: string }>("llm:plan-approval-resolved", (e) => {
-        if (e.payload.sessionId !== activeSessionRef.current) return;
-        setActivePlanApproval(null);
-      }),
-      listen<{ sessionId: string }>("llm:planning-start", (e) => {
-        if (e.payload.sessionId !== activeSessionRef.current) return;
-        setIsPlanning(true);
-      }),
-      listen<{ sessionId: string; planText: string }>("llm:planning-done", (e) => {
-        if (e.payload.sessionId !== activeSessionRef.current) return;
-        setIsPlanning(false);
-        const planText = e.payload.planText;
-        if (planText && planText.trim()) {
-          setMessages((prev) => {
-            const next = [...prev];
-            const last = next[next.length - 1];
-            if (last?.role === "assistant" && last.streaming) {
-              next[next.length - 1] = {
-                ...last,
-                content: "",
-                meta: { ...last.meta, planningText: planText },
-              };
-            }
-            return next;
-          });
-        }
-      }),
-      listen<{ sessionId: string; steps: { step: number; title: string }[] }>("llm:plan-steps", (e) => {
-        if (e.payload.sessionId !== activeSessionRef.current) return;
-        activeStepRef.current = null;
-        const planSteps: PlanStepInfo[] = e.payload.steps.map((s) => ({
-          step: s.step,
-          title: s.title,
-          status: "pending" as const,
-          toolCalls: [],
-        }));
-        setMessages((prev) => {
-          const next = [...prev];
-          const last = next[next.length - 1];
-          if (last?.role === "assistant") {
-            next[next.length - 1] = {
-              ...last,
-              meta: { ...last.meta, planSteps },
-            };
-          }
-          return next;
-        });
-      }),
-      listen<{ sessionId: string; step: number; status: string }>("llm:plan-step-update", (e) => {
-        if (e.payload.sessionId !== activeSessionRef.current) return;
-        const { step, status } = e.payload;
-        if (status === "in_progress") {
-          activeStepRef.current = step;
-        }
-        setMessages((prev) => {
-          const next = [...prev];
-          for (let i = next.length - 1; i >= 0; i--) {
-            const m = next[i];
-            if (m.role !== "assistant" || !m.meta?.planSteps) continue;
-            const steps = m.meta.planSteps.map((s) =>
-              s.step === step
-                ? { ...s, status: status as PlanStepInfo["status"] }
-                : s,
-            );
-            next[i] = { ...m, meta: { ...m.meta, planSteps: steps } };
-            break;
-          }
-          return next;
-        });
+        setMessages((prev) =>
+          findAndPatchToolCall(prev, p.parentToolCallId, (tc) => ({
+            ...tc,
+            skillId: p.skillId,
+            skillName: p.skillName,
+            skillContent: "",
+            skillToolCalls: [],
+            skillStreaming: true,
+          })) ?? prev,
+        );
       }),
       // Budget warning: tool call budget reaching 80%
       listen<{ sessionId: string; used: number; limit: number; type: string }>(
@@ -1289,23 +1121,12 @@ export function AiConversationPanel() {
           }
           parentSessionRef.current = null;
 
-          setMessages((prev) => {
-            const next = [...prev];
-            for (let i = next.length - 1; i >= 0; i--) {
-              const m = next[i];
-              if (m.role !== "assistant") continue;
-              const tcs = m.meta?.toolCalls;
-              if (!tcs) continue;
-              const tcIdx = tcs.findIndex((tc) => tc.toolCallId === skillMapping.parentToolCallId);
-              if (tcIdx === -1) continue;
-
-              const updatedCalls = [...tcs];
-              updatedCalls[tcIdx] = { ...updatedCalls[tcIdx], skillStreaming: false };
-              next[i] = { ...m, meta: { ...m.meta, toolCalls: updatedCalls } };
-              break;
-            }
-            return next;
-          });
+          setMessages((prev) =>
+            findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+              ...tc,
+              skillStreaming: false,
+            })) ?? prev,
+          );
           return;
         }
 
@@ -1318,10 +1139,8 @@ export function AiConversationPanel() {
         markNeedPersist();
         activeSessionRef.current = null;
         isAgentModeRef.current = false;
-        activeStepRef.current = null;
         setIsStreaming(false);
         setIsVaultSearching(false);
-        setIsPlanning(false);
         setMessages((prev) => {
           const next = [...prev];
           const last = next[next.length - 1];
@@ -2206,12 +2025,6 @@ export function AiConversationPanel() {
         </div>
       ) : null}
 
-      {isPlanning ? (
-        <div className="ai-chat__banner ai-chat__banner--hint" aria-live="polite" {...dragExcludeProps}>
-          {t("aiPanel.planning")}
-        </div>
-      ) : null}
-
       {passiveHighlightBanner ? (
         <div
           className="ai-chat__banner ai-chat__banner--hint ai-chat__banner--dismissible"
@@ -2259,103 +2072,7 @@ export function AiConversationPanel() {
               <div className={`ai-chat__bubble ai-chat__bubble--${m.role}`}>
                 {m.role === "assistant" ? (
                   <>
-                    {m.meta?.planSteps && m.meta.planSteps.length > 0 ? (
-                      <div className="ai-chat__plan-progress">
-                        {m.meta.planSteps.map((ps) => (
-                          <details
-                            key={ps.step}
-                            className={`ai-chat__plan-step ai-chat__plan-step--${ps.status}`}
-                            open={ps.status === "in_progress"}
-                          >
-                            <summary className="ai-chat__plan-step__header">
-                              <span className="ai-chat__plan-step__icon" aria-hidden={true}>
-                                {ps.status === "done" ? "✓" : ps.status === "in_progress" ? "⋯" : "○"}
-                              </span>
-                              <span className="ai-chat__plan-step__number">{ps.step}.</span>
-                              <span className="ai-chat__plan-step__title">{ps.title}</span>
-                            </summary>
-                            {ps.toolCalls.length > 0 && (
-                              <div className="ai-chat__tool-calls ai-chat__plan-step__tools">
-                                {ps.toolCalls.map((tc) => (
-                                  <details key={tc.toolCallId} className="ai-chat__tool-call-details">
-                                    <summary className={`ai-chat__tool-call ai-chat__tool-call--${tc.status}`}>
-                                      <span className="ai-chat__tool-call__icon" aria-hidden={true}>
-                                        {tc.status === "running" ? "⋯" : tc.status === "done" ? "✓" : "✗"}
-                                      </span>
-                                      <span className="ai-chat__tool-call__name">{tc.toolName}</span>
-                                      {tc.durationMs != null && (
-                                        <span className="ai-chat__tool-call__duration">
-                                          {(tc.durationMs / 1000).toFixed(1)}s
-                                        </span>
-                                      )}
-                                    </summary>
-                                    <div className="ai-chat__tool-call__detail">
-                                      {tc.inputSummary && (
-                                        <div className="ai-chat__tool-call__input">
-                                          <span className="ai-chat__tool-call__label">输入</span>
-                                          <code>{tc.inputSummary}</code>
-                                        </div>
-                                      )}
-                                      {tc.resultSummary && (
-                                        <div className="ai-chat__tool-call__result">
-                                          <span className="ai-chat__tool-call__label">结果</span>
-                                          <code>{tc.resultSummary}</code>
-                                        </div>
-                                      )}
-                                      {tc.errorMessage && (
-                                        <div className="ai-chat__tool-call__error">
-                                          <span className="ai-chat__tool-call__label">错误</span>
-                                          <code>{tc.errorMessage}</code>
-                                        </div>
-                                      )}
-                                    </div>
-                                  </details>
-                                ))}
-                              </div>
-                            )}
-                          </details>
-                        ))}
-                        {m.meta.toolCalls && m.meta.toolCalls.length > 0 ? (
-                          <div className="ai-chat__tool-calls">
-                            {m.meta.toolCalls.map((tc) => (
-                              <details key={tc.toolCallId} className="ai-chat__tool-call-details">
-                                <summary className={`ai-chat__tool-call ai-chat__tool-call--${tc.status}`}>
-                                  <span className="ai-chat__tool-call__icon" aria-hidden={true}>
-                                    {tc.status === "running" ? "⋯" : tc.status === "done" ? "✓" : "✗"}
-                                  </span>
-                                  <span className="ai-chat__tool-call__name">{tc.toolName}</span>
-                                  {tc.durationMs != null && (
-                                    <span className="ai-chat__tool-call__duration">
-                                      {(tc.durationMs / 1000).toFixed(1)}s
-                                    </span>
-                                  )}
-                                </summary>
-                                <div className="ai-chat__tool-call__detail">
-                                  {tc.inputSummary && (
-                                    <div className="ai-chat__tool-call__input">
-                                      <span className="ai-chat__tool-call__label">输入</span>
-                                      <code>{tc.inputSummary}</code>
-                                    </div>
-                                  )}
-                                  {tc.resultSummary && (
-                                    <div className="ai-chat__tool-call__result">
-                                      <span className="ai-chat__tool-call__label">结果</span>
-                                      <code>{tc.resultSummary}</code>
-                                    </div>
-                                  )}
-                                  {tc.errorMessage && (
-                                    <div className="ai-chat__tool-call__error">
-                                      <span className="ai-chat__tool-call__label">错误</span>
-                                      <code>{tc.errorMessage}</code>
-                                    </div>
-                                  )}
-                                </div>
-                              </details>
-                            ))}
-                          </div>
-                        ) : null}
-                      </div>
-                    ) : m.meta?.toolCalls && m.meta.toolCalls.length > 0 ? (
+                    {m.meta?.toolCalls && m.meta.toolCalls.length > 0 ? (
                       <div className="ai-chat__tool-calls">
                         {m.meta.toolCalls.map((tc) => (
                           <details key={tc.toolCallId} className="ai-chat__tool-call-details">
@@ -2363,7 +2080,7 @@ export function AiConversationPanel() {
                               <span className="ai-chat__tool-call__icon" aria-hidden={true}>
                                 {tc.status === "running" ? "⋯" : tc.status === "done" ? "✓" : "✗"}
                               </span>
-                              <span className="ai-chat__tool-call__name">{tc.toolName}</span>
+                              <span className="ai-chat__tool-call__name">{tc.displaySummary || tc.toolName}</span>
                               {tc.durationMs != null && (
                                 <span className="ai-chat__tool-call__duration">
                                   {(tc.durationMs / 1000).toFixed(1)}s
@@ -2390,7 +2107,7 @@ export function AiConversationPanel() {
                                             <span className="ai-chat__tool-call__icon" aria-hidden={true}>
                                               {stc.status === "running" ? "⋯" : stc.status === "done" ? "✓" : "✗"}
                                             </span>
-                                            <span className="ai-chat__tool-call__name">{stc.toolName}</span>
+                                            <span className="ai-chat__tool-call__name">{stc.displaySummary || stc.toolName}</span>
                                             {stc.durationMs != null && (
                                               <span className="ai-chat__tool-call__duration">
                                                 {(stc.durationMs / 1000).toFixed(1)}s
@@ -2445,15 +2162,7 @@ export function AiConversationPanel() {
                         Agent {m.meta.budgetWarning.used}/{m.meta.budgetWarning.limit} tool calls used
                       </div>
                     )}
-                    {!m.meta?.planSteps && m.meta?.planningText && (
-                      <details className="ai-chat__planning-fold">
-                        <summary>Plan</summary>
-                        <AiAssistantMarkdown content={m.meta.planningText} />
-                      </details>
-                    )}
-                    <div className={isPlanning && m.streaming ? "ai-chat__planning-live" : undefined}>
-                      <AiAssistantMarkdown content={m.content} />
-                    </div>
+                    <AiAssistantMarkdown content={m.content} />
                     {!m.streaming && m.meta?.thoughtCitation && !m.meta.thoughtCitation.privateOmitted ? (
                       <button
                         type="button"
@@ -2856,11 +2565,6 @@ export function AiConversationPanel() {
       ) : null}
 
       <AiToolApprovalDialog request={activeApproval} onResolve={handleApprovalResolve} />
-      <AiPlanApprovalDialog
-        request={activePlanApproval}
-        onApprove={handlePlanApprove}
-        onReject={handlePlanReject}
-      />
     </section>
   );
 }
diff --git a/src/components/AiLlmSettingsModal.tsx b/src/components/AiLlmSettingsModal.tsx
index d8b4414..d9cf649 100644
--- a/src/components/AiLlmSettingsModal.tsx
+++ b/src/components/AiLlmSettingsModal.tsx
@@ -144,7 +144,6 @@ type FormState = {
   allowPrivateContentInLocalLlm: boolean;
   toolsEnabled: boolean;
   planningEnabled: boolean;
-  planningApprovalEnabled: boolean;
   memoryEnabled: boolean;
   memoryReflectionMode: string;
   passiveHighlightEnabled: boolean;
@@ -253,7 +252,6 @@ function defaultForm(): FormState {
     allowPrivateContentInLocalLlm: false,
     toolsEnabled: true,
     planningEnabled: false,
-    planningApprovalEnabled: true,
     memoryEnabled: true,
     memoryReflectionMode: "confirm",
     passiveHighlightEnabled: true,
@@ -304,7 +302,6 @@ function aiFormEqualsPersisted(a: FormState, b: FormState): boolean {
     "allowPrivateContentInLocalLlm",
     "toolsEnabled",
     "planningEnabled",
-    "planningApprovalEnabled",
     "memoryEnabled",
     "memoryReflectionMode",
     "passiveHighlightEnabled",
@@ -367,7 +364,6 @@ function vaultConfigToForm(cfg: VaultConfigForUi): FormState {
     allowPrivateContentInLocalLlm: ai.privacy.allowPrivateContentInLocalLlm,
     toolsEnabled: ai.toolsEnabled !== false,
     planningEnabled: ai.planningEnabled === true,
-    planningApprovalEnabled: ai.planningApprovalEnabled !== false,
     memoryEnabled: ai.memoryEnabled !== false,
     memoryReflectionMode: ai.memoryReflectionMode ?? "confirm",
     passiveHighlightEnabled: cognitive.passiveHighlightEnabled !== false,
@@ -785,7 +781,6 @@ export function AiLlmSettingsModal({
         },
         toolsEnabled: form.toolsEnabled,
         planningEnabled: form.planningEnabled,
-        planningApprovalEnabled: form.planningApprovalEnabled,
         memoryEnabled: form.memoryEnabled,
         memoryReflectionMode: form.memoryReflectionMode,
       },
@@ -1304,29 +1299,6 @@ export function AiLlmSettingsModal({
                 {t("settings.planningEnabled")}
               </label>
               <p className="app-modal__hint">{t("settings.planningEnabledHint")}</p>
-              {form.planningEnabled && (
-                <>
-                  <label
-                    className="ai-settings__check"
-                    title={t("settings.planningApprovalEnabledHint")}
-                  >
-                    <input
-                      type="checkbox"
-                      checked={form.planningApprovalEnabled}
-                      onChange={(e) =>
-                        setForm((f) => ({
-                          ...f,
-                          planningApprovalEnabled: e.target.checked,
-                        }))
-                      }
-                    />
-                    {t("settings.planningApprovalEnabled")}
-                  </label>
-                  <p className="app-modal__hint">
-                    {t("settings.planningApprovalEnabledHint")}
-                  </p>
-                </>
-              )}
               <label className="ai-settings__check" title={t("settings.memoryEnabledHint")}>
                 <input
                   type="checkbox"
diff --git a/src/components/AiPlanApprovalDialog.css b/src/components/AiPlanApprovalDialog.css
deleted file mode 100644
index 324d234..0000000
--- a/src/components/AiPlanApprovalDialog.css
+++ /dev/null
@@ -1,156 +0,0 @@
-.plan-approval-overlay {
-  position: absolute;
-  inset: 0;
-  z-index: 110;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: rgba(0, 0, 0, 0.4);
-  backdrop-filter: blur(2px);
-}
-
-.plan-approval-overlay__card {
-  width: min(560px, calc(100% - 32px));
-  margin: 0 16px;
-  padding: 20px 22px;
-  background: #fff;
-  border-radius: 12px;
-  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-  max-height: calc(100% - 32px);
-  overflow: hidden;
-}
-
-.plan-approval-overlay__header {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-}
-
-.plan-approval-overlay__title {
-  margin: 0;
-  font-size: 0.95rem;
-  font-weight: 600;
-  color: #111827;
-}
-
-.plan-approval-overlay__description {
-  margin: 0;
-  font-size: 0.85rem;
-  line-height: 1.5;
-  color: #374151;
-}
-
-.plan-approval-overlay__plan {
-  padding: 10px 14px;
-  background: #f9fafb;
-  border: 1px solid #e5e7eb;
-  border-radius: 8px;
-  font-size: 0.85rem;
-  color: #1f2937;
-  overflow-y: auto;
-  flex: 1 1 auto;
-  min-height: 80px;
-  max-height: 45vh;
-}
-
-.plan-approval-overlay__actions {
-  display: flex;
-  flex-direction: row;
-  justify-content: flex-end;
-  gap: 8px;
-  margin-top: 4px;
-}
-
-.plan-approval-overlay__btn {
-  min-width: 90px;
-  padding: 7px 14px;
-  font-size: 0.8rem;
-  line-height: 1.4;
-  border-radius: 6px;
-  border: 1px solid transparent;
-  cursor: pointer;
-  transition: background 0.15s, box-shadow 0.15s;
-}
-
-.plan-approval-overlay__btn:disabled {
-  opacity: 0.5;
-  cursor: not-allowed;
-}
-
-.plan-approval-overlay__btn--approve {
-  background: #2563eb;
-  color: #fff;
-  border-color: #1d4ed8;
-}
-
-.plan-approval-overlay__btn--approve:hover:not(:disabled) {
-  background: #1d4ed8;
-}
-
-.plan-approval-overlay__btn--approve:focus-visible {
-  outline: 2px solid #60a5fa;
-  outline-offset: 2px;
-}
-
-.plan-approval-overlay__btn--reject {
-  background: transparent;
-  color: #6b7280;
-  border-color: #d1d5db;
-  margin-right: auto;
-}
-
-.plan-approval-overlay__btn--reject:hover {
-  background: #f3f4f6;
-}
-
-.plan-approval-overlay__btn--reject:focus-visible {
-  outline: 2px solid #9ca3af;
-  outline-offset: 2px;
-}
-
-/* ---- dark mode ---- */
-@media (prefers-color-scheme: dark) {
-  .plan-approval-overlay {
-    background: rgba(0, 0, 0, 0.55);
-  }
-
-  .plan-approval-overlay__card {
-    background: #1f2937;
-    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
-  }
-
-  .plan-approval-overlay__title {
-    color: #f3f4f6;
-  }
-
-  .plan-approval-overlay__description {
-    color: #d1d5db;
-  }
-
-  .plan-approval-overlay__plan {
-    background: #111827;
-    border-color: #374151;
-    color: #e5e7eb;
-  }
-
-  .plan-approval-overlay__btn--approve {
-    background: #3b82f6;
-    border-color: #2563eb;
-  }
-
-  .plan-approval-overlay__btn--approve:hover:not(:disabled) {
-    background: #2563eb;
-  }
-
-  .plan-approval-overlay__btn--reject {
-    color: #9ca3af;
-    border-color: #4b5563;
-  }
-
-  .plan-approval-overlay__btn--reject:hover {
-    background: rgba(255, 255, 255, 0.06);
-  }
-}
diff --git a/src/components/AiPlanApprovalDialog.tsx b/src/components/AiPlanApprovalDialog.tsx
deleted file mode 100644
index 92476db..0000000
--- a/src/components/AiPlanApprovalDialog.tsx
+++ /dev/null
@@ -1,73 +0,0 @@
-import { useCallback } from "react";
-import { useTranslation } from "react-i18next";
-
-import type { PlanApprovalRequest } from "../types/toolTypes";
-import { AiAssistantMarkdown } from "./AiAssistantMarkdown";
-import "./AiPlanApprovalDialog.css";
-
-interface AiPlanApprovalDialogProps {
-  request: PlanApprovalRequest | null;
-  onApprove: (approvalId: string) => void;
-  onReject: (approvalId: string) => void;
-}
-
-export function AiPlanApprovalDialog({
-  request,
-  onApprove,
-  onReject,
-}: AiPlanApprovalDialogProps) {
-  const { t } = useTranslation();
-
-  const approve = useCallback(() => {
-    if (request) onApprove(request.approvalId);
-  }, [request, onApprove]);
-
-  const reject = useCallback(() => {
-    if (request) onReject(request.approvalId);
-  }, [request, onReject]);
-
-  if (!request) return null;
-
-  return (
-    <div
-      className="plan-approval-overlay"
-      role="alertdialog"
-      aria-modal="true"
-      aria-label={t("aiPanel.planApprovalTitle")}
-    >
-      <div className="plan-approval-overlay__card">
-        <div className="plan-approval-overlay__header">
-          <h3 className="plan-approval-overlay__title">
-            {t("aiPanel.planApprovalTitle")}
-          </h3>
-        </div>
-
-        <p className="plan-approval-overlay__description">
-          {t("aiPanel.planApprovalDescription")}
-        </p>
-
-        <div className="plan-approval-overlay__plan">
-          <AiAssistantMarkdown content={request.planText} />
-        </div>
-
-        <div className="plan-approval-overlay__actions">
-          <button
-            type="button"
-            className="plan-approval-overlay__btn plan-approval-overlay__btn--reject"
-            onClick={reject}
-          >
-            {t("aiPanel.planApprovalReject")}
-          </button>
-          <button
-            type="button"
-            className="plan-approval-overlay__btn plan-approval-overlay__btn--approve"
-            onClick={approve}
-            autoFocus
-          >
-            {t("aiPanel.planApprovalRun")}
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-}
diff --git a/src/hooks/useWorkspaceAiConversations.ts b/src/hooks/useWorkspaceAiConversations.ts
index 247c2a1..7679862 100644
--- a/src/hooks/useWorkspaceAiConversations.ts
+++ b/src/hooks/useWorkspaceAiConversations.ts
@@ -6,6 +6,7 @@ import type {
   ConversationMeta,
   ListAiConversationsResponse,
   PersistedChatMessage,
+  PersistedToolCall,
   ThoughtFocusContext,
 } from "../types/aiConversation";
 import type { ThoughtRetrievalResult } from "../types/cognitiveTypes";
@@ -22,6 +23,7 @@ export type ChatMessageTiming = {
 export type ToolCallDisplayInfo = {
   toolCallId: string;
   toolName: string;
+  displaySummary?: string;
   status: "running" | "done" | "error";
   /** 可解释性字段 */
   inputSummary?: string;
@@ -36,13 +38,6 @@ export type ToolCallDisplayInfo = {
   skillStreaming?: boolean;
 };
 
-export type PlanStepInfo = {
-  step: number;
-  title: string;
-  status: "pending" | "in_progress" | "done";
-  toolCalls: ToolCallDisplayInfo[];
-};
-
 export type ChatMessage = {
   id: string;
   role: "user" | "assistant";
@@ -68,17 +63,36 @@ export type ChatMessage = {
      *  即使关闭并重新打开 vault，徽章和过滤行为均保持一致。 */
     skillId?: string;
     skillName?: string;
-    planningText?: string;
-    planSteps?: PlanStepInfo[];
   };
 };
 
+function normalizeToolCallForPersist(tc: ToolCallDisplayInfo): PersistedToolCall {
+  const result: PersistedToolCall = {
+    toolCallId: tc.toolCallId,
+    toolName: tc.toolName,
+    displaySummary: tc.displaySummary,
+    status: tc.status === "running" ? "done" : (tc.status as "done" | "error"),
+    inputSummary: tc.inputSummary,
+    resultSummary: tc.resultSummary,
+    durationMs: tc.durationMs,
+    errorMessage: tc.errorMessage,
+    skillId: tc.skillId,
+    skillName: tc.skillName,
+    skillContent: tc.skillContent,
+  };
+  if (tc.skillToolCalls && tc.skillToolCalls.length > 0) {
+    result.skillToolCalls = tc.skillToolCalls.map(normalizeToolCallForPersist);
+  }
+  return result;
+}
+
 function bodyToMessages(body: ConversationBodyOut): ChatMessage[] {
   return body.messages.map((m) => {
     const meta: ChatMessage["meta"] = {};
     if (m.replyContextSources) meta.replyContextSources = m.replyContextSources;
     if (m.skillId) meta.skillId = m.skillId;
     if (m.skillName) meta.skillName = m.skillName;
+    if (m.toolCalls) meta.toolCalls = m.toolCalls as unknown as ToolCallDisplayInfo[];
     return {
       id: m.id,
       role: m.role === "assistant" ? ("assistant" as const) : ("user" as const),
@@ -91,14 +105,20 @@ function bodyToMessages(body: ConversationBodyOut): ChatMessage[] {
 function toPersistPayload(messages: ChatMessage[]): PersistedChatMessage[] {
   return messages
     .filter((m) => !m.streaming)
-    .map((m) => ({
-      id: m.id,
-      role: m.role,
-      content: m.content,
-      replyContextSources: m.meta?.replyContextSources,
-      skillId: m.meta?.skillId,
-      skillName: m.meta?.skillName,
-    }));
+    .map((m) => {
+      const msg: PersistedChatMessage = {
+        id: m.id,
+        role: m.role,
+        content: m.content,
+        replyContextSources: m.meta?.replyContextSources,
+        skillId: m.meta?.skillId,
+        skillName: m.meta?.skillName,
+      };
+      if (m.meta?.toolCalls && m.meta.toolCalls.length > 0) {
+        msg.toolCalls = m.meta.toolCalls.map(normalizeToolCallForPersist);
+      }
+      return msg;
+    });
 }
 
 type CreateResponse = { id: string };
diff --git a/src/locales/en.json b/src/locales/en.json
index ce30155..06ff4ba 100644
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -332,10 +332,6 @@
     "toolApprovalPolicyLabel": "Approval scope",
     "toolApprovalPolicyOnce": "Once per conversation",
     "toolApprovalPolicyEach": "Each invocation",
-    "planApprovalTitle": "Review plan before running",
-    "planApprovalDescription": "The assistant produced an execution plan. Run it, or reject and refine your prompt before resending.",
-    "planApprovalRun": "Run",
-    "planApprovalReject": "Reject",
     "skillBadge": "Skill: {{name}}",
     "skillUnknown": "Unknown skill: {{id}}. Type / to see available skills, or use /skills to list them.",
     "skillInvokeFailed": "Failed to invoke skill: {{message}}",
@@ -505,8 +501,6 @@
     "planningSection": "Planning mode",
     "planningEnabled": "Enable planning before tool execution",
     "planningEnabledHint": "When enabled, the AI plans tool calls before executing them using the active provider.",
-    "planningApprovalEnabled": "Review plan before running",
-    "planningApprovalEnabledHint": "When enabled, the AI pauses after producing a plan so you can run, edit, or reject it. When off, the plan runs automatically.",
     "memoryEnabled": "Enable agent memory",
     "memoryEnabledHint": "When enabled, the AI remembers your knowledge domains, interaction style, and corrections across conversations to provide more personalized responses.",
     "clearMemory": "Clear all memory",
diff --git a/src/locales/zh.json b/src/locales/zh.json
index 106496e..a1474ea 100644
--- a/src/locales/zh.json
+++ b/src/locales/zh.json
@@ -332,10 +332,6 @@
     "toolApprovalPolicyLabel": "审批范围",
     "toolApprovalPolicyOnce": "本会话仅询问一次",
     "toolApprovalPolicyEach": "每次调用都询问",
-    "planApprovalTitle": "执行前审核计划",
-    "planApprovalDescription": "助手已生成执行计划。可以直接执行；若不认可，请拒绝并修改提示词后重发。",
-    "planApprovalRun": "执行",
-    "planApprovalReject": "拒绝",
     "skillBadge": "技能：{{name}}",
     "skillUnknown": "未知技能：{{id}}。输入 / 查看可用技能，或用 /skills 列出全部。",
     "skillInvokeFailed": "调用技能失败：{{message}}",
@@ -505,8 +501,6 @@
     "planningSection": "规划模式",
     "planningEnabled": "工具执行前先做规划",
     "planningEnabledHint": "开启后，AI 在调用工具前会先制定计划，使用当前活跃的模型服务。",
-    "planningApprovalEnabled": "执行前审核计划",
-    "planningApprovalEnabledHint": "开启后，AI 生成计划会先暂停等待你确认，可执行、编辑后执行或拒绝。关闭则计划生成后自动执行。",
     "memoryEnabled": "启用 Agent 记忆",
     "memoryEnabledHint": "开启后，AI 会跨对话记住你的知识领域、交互风格和纠正信息，提供更个性化的回答。",
     "clearMemory": "清除全部记忆",
diff --git a/src/types/aiConversation.ts b/src/types/aiConversation.ts
index 789df6f..546d896 100644
--- a/src/types/aiConversation.ts
+++ b/src/types/aiConversation.ts
@@ -9,6 +9,21 @@ export type ConversationMeta = {
   updatedAt: number;
 };
 
+export type PersistedToolCall = {
+  toolCallId: string;
+  toolName: string;
+  displaySummary?: string;
+  status: "done" | "error";
+  inputSummary?: string;
+  resultSummary?: string;
+  durationMs?: number;
+  errorMessage?: string;
+  skillId?: string;
+  skillName?: string;
+  skillContent?: string;
+  skillToolCalls?: PersistedToolCall[];
+};
+
 export type PersistedChatMessage = {
   id: string;
   role: "user" | "assistant";
@@ -20,6 +35,7 @@ export type PersistedChatMessage = {
    *  (b) 主对话发送时按此过滤掉 skill 子轮次，避免污染 prompt context。 */
   skillId?: string;
   skillName?: string;
+  toolCalls?: PersistedToolCall[];
 };
 
 /** 与 Rust `ThoughtFocusContextDisk` / LLM `thought_focus_context` 对齐 */
diff --git a/src/types/toolTypes.ts b/src/types/toolTypes.ts
index 70a5f23..5d81d08 100644
--- a/src/types/toolTypes.ts
+++ b/src/types/toolTypes.ts
@@ -115,14 +115,3 @@ export interface ApprovalRequest {
   effects: Effect[];
 }
 
-// 后端在 Planning 模式下、Phase A 生成计划后、Phase B 执行前 emit
-// `llm:plan-approval-request`，前端展示审批卡片；用户可执行或拒绝，
-// 通过 `respond_plan_approval` 回送。计划不可编辑——不认可应拒绝并修改提示词重发。
-export interface PlanApprovalRequest {
-  sessionId: string;
-  conversationId: string;
-  approvalId: string;
-  planText: string;
-}
-
-export type PlanApprovalDecision = "approve" | "reject";
diff --git a/src/types/vaultAiConfig.ts b/src/types/vaultAiConfig.ts
index 2fad7ce..3669381 100644
--- a/src/types/vaultAiConfig.ts
+++ b/src/types/vaultAiConfig.ts
@@ -41,7 +41,6 @@ export type AiConfigForUi = {
   privacy: AiPrivacy;
   toolsEnabled: boolean;
   planningEnabled: boolean;
-  planningApprovalEnabled: boolean;
   memoryEnabled: boolean;
   memoryReflectionMode: string;
 };
@@ -103,7 +102,6 @@ export type AiConfigSavePatch = {
   };
   toolsEnabled?: boolean;
   planningEnabled?: boolean;
-  planningApprovalEnabled?: boolean;
   memoryEnabled?: boolean;
   memoryReflectionMode?: string;
 };
diff --git a/src/utils/toolInvoke.ts b/src/utils/toolInvoke.ts
index 15af6d3..9c31cab 100644
--- a/src/utils/toolInvoke.ts
+++ b/src/utils/toolInvoke.ts
@@ -3,7 +3,6 @@
 
 import { invoke } from "@tauri-apps/api/core";
 import type {
-  PlanApprovalDecision,
   ToolManifestJson,
   ToolResultErr,
   ToolResultJson,
@@ -63,18 +62,6 @@ export async function respondToolApproval(
   return invoke<void>("respond_tool_approval", { args: { approvalId, decision } });
 }
 
-/**
- * 回送计划审批结果（执行 / 拒绝）。
- */
-export async function respondPlanApproval(
-  approvalId: string,
-  decision: PlanApprovalDecision,
-): Promise<void> {
-  return invoke<void>("respond_plan_approval", {
-    args: { approvalId, decision },
-  });
-}
-
 /**
  * 切换/删除会话时清理 ConfirmOncePerSession 会话级缓存。
  */

From 291364c4d95a3edc12fb3766db8a716647859c64 Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Fri, 3 Jul 2026 17:29:54 +0800
Subject: [PATCH 06/10] refactor(ui): extract ToolCallItem, MessageBubble,
 useAgentEventHandlers from AiConversationPanel

Break 2570-line God Component into focused modules:
- ToolCallItem (54 lines): self-recursive tool call renderer
- MessageBubble (160 lines): single message render logic
- useAgentEventHandlers (734 lines): 11 Tauri event listeners + session refs

AiConversationPanel reduced from 2570 to 1758 lines (-31.6%).

Co-authored-by: Claude (Opus 4.6) <noreply@anthropic.com>
---
 src/components/AiConversationPanel.tsx | 908 ++-----------------------
 src/components/MessageBubble.tsx       | 160 +++++
 src/components/ToolCallItem.tsx        |  54 ++
 src/hooks/useAgentEventHandlers.ts     | 734 ++++++++++++++++++++
 4 files changed, 996 insertions(+), 860 deletions(-)
 create mode 100644 src/components/MessageBubble.tsx
 create mode 100644 src/components/ToolCallItem.tsx
 create mode 100644 src/hooks/useAgentEventHandlers.ts

diff --git a/src/components/AiConversationPanel.tsx b/src/components/AiConversationPanel.tsx
index f06ab63..c895d58 100644
--- a/src/components/AiConversationPanel.tsx
+++ b/src/components/AiConversationPanel.tsx
@@ -1,22 +1,19 @@
 import { invoke, isTauri } from "@tauri-apps/api/core";
-import { listen, type UnlistenFn } from "@tauri-apps/api/event";
 import { useCallback, useEffect, useMemo, useRef, useState, type KeyboardEvent } from "react";
 import { useTranslation } from "react-i18next";
 import { useAiConversationSession } from "../contexts/AiConversationSessionContext";
 import type { ThoughtFocusContext } from "../types/aiConversation";
 import { useAiNoteContext } from "../contexts/AiNoteContext";
-import type { ChatMessage, ToolCallDisplayInfo } from "../hooks/useWorkspaceAiConversations";
+import type { ChatMessage } from "../hooks/useWorkspaceAiConversations";
+import { useAgentEventHandlers, retractInterruptedTurn, finalizeStreamingAssistant } from "../hooks/useAgentEventHandlers";
 import type { ReplyContextSources } from "../types/replyContextSources";
 import { hasReplyContextSourcesToShow } from "../types/replyContextSources";
 import type {
   AutoResolvedDepth,
   ThoughtRetrievalResult,
-  CountVaultThoughtsForReviewResponse,
-  GenerateChallengeQuestionResponse,
 } from "../types/cognitiveTypes";
 import type { DetectPassiveHighlightResponse, PassiveHighlightMarked } from "../types/passiveHighlight";
 import type { VaultConfigForUi, ProviderProfileForUi } from "../types/vaultAiConfig";
-import { isChallengeInlineLlmReady } from "../utils/isChallengeReviewLlmReady";
 import { VAULT_CONFIG_UPDATED_EVENT } from "../utils/vaultConfigBroadcast";
 import { markdownTreatAsKfPrivateForUi } from "../utils/kfPrivateMarkdown";
 import { PrivacyChangeOverlay } from "./PrivacyChangeOverlay";
@@ -26,18 +23,14 @@ import { respondToolApproval } from "../utils/toolInvoke";
 import { listSkills, invokeSkill } from "../utils/skillInvoke";
 import type { SkillManifestJson } from "../types/skillTypes";
 import { parseSlashCommand } from "../utils/parseSlashCommand";
-import { AiAssistantMarkdown } from "./AiAssistantMarkdown";
-import { StreamingTimer } from "./StreamingTimer";
+import { MessageBubble, IconSaveThought } from "./MessageBubble";
 import { useCognitiveFrequencyControl } from "../hooks/useCognitiveFrequencyControl";
 import { DepthSlider } from "./DepthSlider";
 import { ChallengeReviewInline } from "./ChallengeReviewInline";
 import { InviteAfterAnswer } from "./InviteAfterAnswer";
 import { ThoughtSavePopover } from "./ThoughtSavePopover";
-import { PassiveHighlightSaveCue } from "./PassiveHighlightSaveCue";
-import { AiReplyContextSources } from "./AiReplyContextSources";
 import { stripMarkedPassiveHighlightWithCount } from "../utils/passiveHighlightLifecycle";
 import { trackKnowforgeEvent } from "../utils/knowforgeAnalytics";
-import { getAppLocale } from "../i18n";
 import "./AiConversationPanel.css";
 import "./MemoryProposals.css";
 
@@ -56,79 +49,6 @@ type MemoryProposalBatch = {
   created_at: string;
 };
 
-/** 用户中止且输入框无新草稿：去掉末尾 streaming 助手及其前一条用户消息 */
-function retractInterruptedTurn(prev: ChatMessage[]): ChatMessage[] {
-  const next = [...prev];
-  const last = next[next.length - 1];
-  if (last?.role === "assistant" && last.streaming) {
-    next.pop();
-  }
-  const u = next[next.length - 1];
-  if (u?.role === "user") {
-    next.pop();
-  }
-  return next;
-}
-
-/** 用户中止但保留会话：仅将末尾 streaming 助手标为结束，保留已生成片段 */
-function finalizeStreamingAssistant(prev: ChatMessage[]): ChatMessage[] {
-  const next = [...prev];
-  const last = next[next.length - 1];
-  if (last?.role === "assistant" && last.streaming) {
-    next[next.length - 1] = { ...last, streaming: false };
-  }
-  return next;
-}
-
-/**
- * Search for a ToolCallDisplayInfo by toolCallId in flat toolCalls.
- * When found, apply the patcher and return the updated messages array.
- * Returns null if not found.
- */
-function findAndPatchToolCall(
-  prev: ChatMessage[],
-  targetToolCallId: string,
-  patcher: (tc: ToolCallDisplayInfo) => ToolCallDisplayInfo,
-): ChatMessage[] | null {
-  for (let i = prev.length - 1; i >= 0; i--) {
-    const m = prev[i];
-    if (m.role !== "assistant") continue;
-
-    const tcs = m.meta?.toolCalls;
-    if (tcs) {
-      const tcIdx = tcs.findIndex((tc) => tc.toolCallId === targetToolCallId);
-      if (tcIdx !== -1) {
-        const next = [...prev];
-        const updated = [...tcs];
-        updated[tcIdx] = patcher(updated[tcIdx]);
-        next[i] = { ...m, meta: { ...m.meta, toolCalls: updated } };
-        return next;
-      }
-    }
-  }
-  return null;
-}
-
-/**
- * 合并流式增量，兼容重复监听或上游偶发返回「全量片段」导致的重复拼接。
- * - `delta` 与当前尾部完全重复：忽略；
- * - `delta` 以当前全文开头：视为全量快照，直接替换为 `delta`；
- * - 其余情况按最大前后缀重叠合并，避免出现「您您 在在」这类叠字。
- */
-function mergeStreamDelta(current: string, delta: string): string {
-  if (!delta) return current;
-  if (!current) return delta;
-  if (current.endsWith(delta)) return current;
-  if (delta.startsWith(current)) return delta;
-
-  const maxOverlap = Math.min(current.length, delta.length);
-  for (let overlap = maxOverlap; overlap > 0; overlap -= 1) {
-    if (current.endsWith(delta.slice(0, overlap))) {
-      return current + delta.slice(overlap);
-    }
-  }
-  return current + delta;
-}
 
 type StartStreamResponse = {
   sessionId: string;
@@ -188,44 +108,6 @@ function IconStopSquare() {
   );
 }
 
-/** 复制助手消息为 Markdown */
-function IconCopyClipboard() {
-  return (
-    <svg
-      width="16"
-      height="16"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden={true}
-    >
-      <rect width="14" height="14" x="8" y="8" rx="2" ry="2" />
-      <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
-    </svg>
-  );
-}
-
-/** 保存为想法图标（书签） */
-function IconSaveThought() {
-  return (
-    <svg
-      width="16"
-      height="16"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden={true}
-    >
-      <path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z" />
-    </svg>
-  );
-}
 
 /** 横幅提示手动关闭（X） */
 function IconDismissBanner() {
@@ -331,7 +213,6 @@ export function AiConversationPanel() {
   const [vaultSearchSummary, setVaultSearchSummary] = useState<string | null>(null);
 
 
-  const activeSessionRef = useRef<string | null>(null);
   const listEndRef = useRef<HTMLDivElement>(null);
   /** 是否吸附在底部：用户向上滚动查看历史时置 false，避免流式刷新强制拉回底部 */
   const stickToBottomRef = useRef(true);
@@ -339,15 +220,6 @@ export function AiConversationPanel() {
   /** Iter 5 #4：工具调用总开关从 vault config 读取（默认 true,旧 vault 缺字段时取 true）。
    *  通过 VAULT_CONFIG_UPDATED_EVENT 在设置保存后实时同步,无需重开会话。 */
   const [toolsEnabled, setToolsEnabled] = useState(true);
-  /** 发送时快照：agent 模式下 stream-done 仅是中间信号，不能最终化助手消息 */
-  const isAgentModeRef = useRef(false);
-
-  /** Iter 5 #4: while a `skill.<id>` auto-invocation is in flight, save the
-   * parent session here so we can restore activeSessionRef once the skill
-   * sub-turn fires `agent-done`. Null when no skill is currently in progress. */
-  const parentSessionRef = useRef<string | null>(null);
-  /** 映射：skillSessionId → { parentToolCallId } */
-  const skillSessionMapRef = useRef<Map<string, { parentToolCallId: string }>>(new Map());
 
   /** Iter 5 #3：内置 skill manifest 缓存。skill 在后端 setup() 注册一次后不变，挂载时取一次即可。 */
   const [skillsCache, setSkillsCache] = useState<SkillManifestJson[]>([]);
@@ -624,566 +496,37 @@ export function AiConversationPanel() {
     }
   }, [messages, scrollToBottom]);
 
-  useEffect(() => {
-    if (!isTauri()) {
-      return;
-    }
-
-    let disposed = false;
-    const pending: UnlistenFn[] = [];
-
-    void Promise.all([
-      listen<{ sessionId: string; delta: string }>("llm:stream-chunk", (e) => {
-        const p = e.payload;
-        if (p.sessionId !== activeSessionRef.current) {
-          return;
-        }
-        const skillMapping = skillSessionMapRef.current.get(p.sessionId);
-        if (skillMapping) {
-          setMessages((prev) =>
-            findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
-              ...tc,
-              skillContent: (tc.skillContent || "") + p.delta,
-            })) ?? prev,
-          );
-          return;
-        }
-        // 主会话的 chunk → 追加到气泡 content（原有逻辑）
-        setMessages((prev) => {
-          let next = [...prev];
-          const last = next[next.length - 1];
-          if (last?.role === "assistant" && last.streaming) {
-            const isFirstToken = last.content === "";
-            next[next.length - 1] = {
-              ...last,
-              content: mergeStreamDelta(last.content, p.delta),
-              meta: isFirstToken && last.meta?.timing
-                ? { ...last.meta, timing: { ...last.meta.timing, firstTokenMs: Date.now() } }
-                : last.meta,
-            };
-          }
-          return next;
-        });
-      }),
-      listen<{ sessionId: string }>("llm:stream-done", (e) => {
-        const p = e.payload;
-        if (p.sessionId !== activeSessionRef.current) {
-          return;
-        }
-        setIsVaultSearching(false);
-        // P2 Tool Calling Loop：agent 模式下 stream-done 只是轮次中的中间信号，
-        // 后续还会有 tool-call-* 与后续文本输出，只能由 llm:agent-done 最终化。
-        if (isAgentModeRef.current) {
-          return;
-        }
-        markNeedPersist();
-        activeSessionRef.current = null;
-        setIsStreaming(false);
-        setMessages((prev) => {
-          const next = [...prev];
-          const last = next[next.length - 1];
-          if (last?.role === "assistant" && last.streaming) {
-            next[next.length - 1] = {
-              ...last,
-              streaming: false,
-              meta: last.meta?.timing
-                ? { ...last.meta, timing: { ...last.meta.timing, endMs: Date.now() } }
-                : last.meta,
-            };
-          }
-          const strippedPack = stripMarkedPassiveHighlightWithCount(next);
-          if (strippedPack.stripped > 0) {
-            passiveHighlightMarkedCountRef.current = Math.max(
-              0,
-              passiveHighlightMarkedCountRef.current - strippedPack.stripped,
-            );
-          }
-          return strippedPack.messages;
-        });
-
-        // 后台：先答后邀优先；否则在满足频控时尝试挑战式回顾（通道二）
-        const epoch = ++inviteSearchEpochRef.current;
-        setInviteData(null);
-        setChallengeInlineData(null);
-        const query = lastSentQueryRef.current.trim();
-        if (!query || enoughForThisChatRef.current) return;
-        const dm = depthModeForInviteRef.current;
-        const ar = autoResolvedForInviteRef.current;
-        if (dm === "shallow" || (dm === "auto" && ar === "shallow")) {
-          return;
-        }
-        void (async () => {
-          try {
-            type SearchResp = {
-              thought: ThoughtRetrievalResult | null;
-              thoughts?: ThoughtRetrievalResult[];
-              meta: { scannedFiles: number; stoppedEarly: boolean; elapsedMs: number };
-            };
-
-            const turnIdx = messagesRef.current.filter((m) => m.role === "user").length;
-            const inviteEligible = freqCtrl.shouldShowInvite(
-              dm,
-              enoughForThisChatRef.current,
-              turnIdx,
-              ar,
-            );
-
-            if (inviteEligible) {
-              const resp = await invoke<SearchResp>("search_thought_for_invite", {
-                args: {
-                  query,
-                  excludeRelPaths: thoughtInviteExcludeRef.current,
-                  maxResults: 1,
-                },
-              });
-              if (inviteSearchEpochRef.current !== epoch || disposed) return;
-              const excerptRaw = resp.thought?.excerpt;
-              const question =
-                excerptRaw && excerptRaw.length > 0
-                  ? t("invite.thoughtQuestion", {
-                      excerpt:
-                        excerptRaw.length > 60 ? `${excerptRaw.slice(0, 60)}...` : excerptRaw,
-                    })
-                  : t("invite.defaultQuestion");
-              setInviteData({ thought: resp.thought, question });
-              attachCitationToLastAssistant(resp.thought ?? null);
-              const th = resp.thought;
-              if (
-                th &&
-                !th.privateOmitted &&
-                th.thoughtId &&
-                isTauri() &&
-                th.relPath
-              ) {
-                void invoke("append_ai_thought_reference", {
-                  args: {
-                    relPath: th.relPath,
-                    thoughtId: th.thoughtId,
-                    context: query.slice(0, 2000),
-                    relevance: "ai-conversation-invite",
-                  },
-                }).catch(() => {});
-              }
-              return;
-            }
-
-            let cfg: VaultCfgForSend;
-            try {
-              cfg = await invoke<VaultCfgForSend>("get_vault_config_for_ui");
-            } catch {
-              return;
-            }
-            if (inviteSearchEpochRef.current !== epoch || disposed) return;
-            if (!isChallengeInlineLlmReady(cfg as VaultConfigForUi)) return;
-
-            const countResp = await invoke<CountVaultThoughtsForReviewResponse>(
-              "count_vault_thoughts_for_review",
-            );
-            if (inviteSearchEpochRef.current !== epoch || disposed) return;
-            const total = countResp.totalThoughts;
-            if (
-              !freqCtrl.shouldShowChallengeInline(dm, ar, {
-                inviteWillShow: false,
-                thoughtId: null,
-                vaultThoughtTotal: total,
-              })
-            ) {
-              return;
-            }
-
-            const respMany = await invoke<SearchResp>("search_thought_for_invite", {
-              args: {
-                query,
-                excludeRelPaths: thoughtInviteExcludeRef.current,
-                maxResults: 3,
-              },
-            });
-            if (inviteSearchEpochRef.current !== epoch || disposed) return;
-            const pick =
-              respMany.thoughts?.find((x) => x.excerpt && !x.privateOmitted) ?? respMany.thought;
-            if (!pick?.excerpt || pick.privateOmitted) return;
-
-            const gen = await invoke<GenerateChallengeQuestionResponse>("generate_challenge_question", {
-              args: {
-                thoughtExcerpt: pick.excerpt,
-                relPath: pick.relPath,
-                conversationQuery: query,
-                depthMode: dm,
-                uiLocale: getAppLocale(),
-              },
-            });
-            if (inviteSearchEpochRef.current !== epoch || disposed) return;
-            if (gen.shouldSkip || !gen.question.trim()) return;
-
-            void freqCtrl.recordChallengeInlineShown(pick.thoughtId);
-            void trackKnowforgeEvent("review.inline_shown", {
-              thoughtId: pick.thoughtId,
-              templateKind: gen.templateKind,
-            });
-            setChallengeInlineData({
-              thought: pick,
-              question: gen.question,
-              templateKind: gen.templateKind,
-            });
-            attachCitationToLastAssistant(pick);
-            if (!pick.privateOmitted && pick.thoughtId && isTauri()) {
-              void invoke("append_ai_thought_reference", {
-                args: {
-                  relPath: pick.relPath,
-                  thoughtId: pick.thoughtId,
-                  context: query.slice(0, 2000),
-                  relevance: "ai-challenge-inline",
-                },
-              }).catch(() => {});
-            }
-          } catch {
-            // 超时或其他失败：静默跳过
-          }
-        })();
-      }),
-      listen<{ sessionId: string; code?: string; message: string }>("llm:stream-error", (e) => {
-        const p = e.payload;
-        if (p.sessionId !== activeSessionRef.current) {
-          return;
-        }
-        // Iter 5 #4: error during a skill sub-turn — restore parent session.
-        // The parent agent_loop will receive the SkillAsTool tool error in its
-        // tool_result and decide whether to recover. Don't tear down top-level streaming UI here.
-        if (parentSessionRef.current) {
-          const parent = parentSessionRef.current;
-          parentSessionRef.current = null;
-          activeSessionRef.current = parent;
-          setMessages((prev) => {
-            const next = [...prev];
-            const last = next[next.length - 1];
-            if (last?.role === "assistant" && last.streaming) {
-              next[next.length - 1] = { ...last, streaming: false };
-            }
-            return next;
-          });
-          return;
-        }
-        markNeedPersist();
-        activeSessionRef.current = null;
-        isAgentModeRef.current = false;
-        setIsStreaming(false);
-        setIsVaultSearching(false);
-        if (p.code === "cancelled") {
-          setMessages((prev) => {
-            if (composerInputRef.current.trim().length > 0) {
-              return finalizeStreamingAssistant(prev);
-            }
-            let lastUser = "";
-            for (let i = prev.length - 1; i >= 0; i--) {
-              if (prev[i].role === "user") {
-                lastUser = prev[i].content;
-                break;
-              }
-            }
-            const next = retractInterruptedTurn(prev);
-            if (lastUser.length > 0) {
-              queueMicrotask(() => setInput(lastUser));
-            }
-            return next;
-          });
-          return;
-        }
-        setMessages((prev) => {
-          const next = [...prev];
-          const last = next[next.length - 1];
-          if (last?.role === "assistant" && last.streaming) {
-            next[next.length - 1] = { ...last, streaming: false };
-          }
-          const strippedPack = stripMarkedPassiveHighlightWithCount(next);
-          if (strippedPack.stripped > 0) {
-            passiveHighlightMarkedCountRef.current = Math.max(
-              0,
-              passiveHighlightMarkedCountRef.current - strippedPack.stripped,
-            );
-          }
-          return strippedPack.messages;
-        });
-        setErrorBanner(p.message);
-      }),
-      // P2 Tool Calling Loop：工具调用开始 → 在末尾 assistant 消息中插入 running 状态项
-      // Skill 内部的工具调用路由到对应 toolCall 的 skillToolCalls
-      listen<{ sessionId: string; toolCallId: string; toolName: string; inputSummary?: string; displaySummary?: string }>(
-        "llm:tool-call-start",
-        (e) => {
-          const p = e.payload;
-          if (p.sessionId !== activeSessionRef.current) {
-            return;
-          }
-          const skillMapping = skillSessionMapRef.current.get(p.sessionId);
-          const newCall: ToolCallDisplayInfo = {
-            toolCallId: p.toolCallId,
-            toolName: p.toolName,
-            displaySummary: p.displaySummary || undefined,
-            status: "running",
-            inputSummary: p.inputSummary,
-          };
-          if (skillMapping) {
-            setMessages((prev) =>
-              findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
-                ...tc,
-                skillToolCalls: [...(tc.skillToolCalls || []), newCall],
-              })) ?? prev,
-            );
-            return;
-          }
-          setMessages((prev) => {
-            const next = [...prev];
-            const last = next[next.length - 1];
-            if (last?.role !== "assistant") return prev;
-            const existing = last.meta?.toolCalls ?? [];
-            return [
-              ...next.slice(0, -1),
-              {
-                ...last,
-                meta: { ...last.meta, toolCalls: [...existing, newCall] },
-              },
-            ];
-          });
-        },
-      ),
-      // P2 Tool Calling Loop：工具调用完成 → 更新对应 toolCallId 的状态为 done/error
-      // 按新字段更新 resultSummary / durationMs / errorMessage，处理 Skill 内部工具调用
-      listen<{ sessionId: string; toolCallId: string; success: boolean; resultSummary?: string; durationMs?: number; errorMessage?: string }>(
-        "llm:tool-call-done",
-        (e) => {
-          const p = e.payload;
-          if (p.sessionId !== activeSessionRef.current) {
-            return;
-          }
-          const skillMapping = skillSessionMapRef.current.get(p.sessionId);
-          if (skillMapping) {
-            setMessages((prev) =>
-              findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
-                ...tc,
-                skillToolCalls: (tc.skillToolCalls || []).map((stc) =>
-                  stc.toolCallId === p.toolCallId
-                    ? { ...stc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
-                    : stc,
-                ),
-              })) ?? prev,
-            );
-            return;
-          }
-          setMessages((prev) => {
-            const patchTc = (tc: ToolCallDisplayInfo): ToolCallDisplayInfo =>
-              tc.toolCallId === p.toolCallId
-                ? { ...tc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
-                : tc;
-
-            for (let i = prev.length - 1; i >= 0; i -= 1) {
-              const m = prev[i];
-              if (m.role !== "assistant") continue;
-
-              if (m.meta?.toolCalls?.some((tc) => tc.toolCallId === p.toolCallId)) {
-                const next = [...prev];
-                next[i] = { ...m, meta: { ...m.meta, toolCalls: m.meta.toolCalls!.map(patchTc) } };
-                return next;
-              }
-            }
-            return prev;
-          });
-        },
-      ),
-      // P3 审批：后端在执行非 Auto 工具前请求用户决策
-      listen<ApprovalRequest>("llm:tool-approval-request", (e) => {
-        const p = e.payload;
-        if (p.sessionId !== activeSessionRef.current) {
-          return;
-        }
-        setActiveApproval((cur) => {
-          if (cur === null) {
-            return p;
-          }
-          approvalQueueRef.current.push(p);
-          return cur;
-        });
-      }),
-      listen<MemoryProposalBatch>("llm:memory-proposals", (e) => {
-        if (e.payload.session_id === activeSessionRef.current) {
-          setMemoryProposals(e.payload);
-          setProposalDecisions({});
-        }
-      }),
-      // Iter 5 #4: 主对话自动调用 `skill.<id>` 时，后端发出 skill-spawn,
-      // 携带新 sessionId — 这里保存父 session、切换 active、更新父气泡中对应工具调用项的 skill 字段。
-      // 不再创建新气泡，Skill 内容内嵌到父气泡的工具调用项中。
-      listen<{
-        sessionId: string;
-        conversationId: string;
-        skillId: string;
-        skillName: string;
-        parentToolCallId: string;
-      }>("llm:skill-spawn", (e) => {
-        const p = e.payload;
-        if (!activeSessionRef.current || activeSessionRef.current === p.sessionId) {
-          return;
-        }
-        if (conversationId && p.conversationId !== conversationId) {
-          return;
-        }
-        parentSessionRef.current = activeSessionRef.current;
-        activeSessionRef.current = p.sessionId;
-        // 记录 skill session → parent tool call 的映射
-        skillSessionMapRef.current.set(p.sessionId, {
-          parentToolCallId: p.parentToolCallId,
-        });
-        setMessages((prev) =>
-          findAndPatchToolCall(prev, p.parentToolCallId, (tc) => ({
-            ...tc,
-            skillId: p.skillId,
-            skillName: p.skillName,
-            skillContent: "",
-            skillToolCalls: [],
-            skillStreaming: true,
-          })) ?? prev,
-        );
-      }),
-      // Budget warning: tool call budget reaching 80%
-      listen<{ sessionId: string; used: number; limit: number; type: string }>(
-        "llm:budget-warning",
-        (e) => {
-          if (e.payload.sessionId !== activeSessionRef.current) return;
-          setMessages((prev) => {
-            const next = [...prev];
-            const last = next[next.length - 1];
-            if (last?.role === "assistant") {
-              next[next.length - 1] = {
-                ...last,
-                meta: {
-                  ...last.meta,
-                  budgetWarning: { used: e.payload.used, limit: e.payload.limit },
-                },
-              };
-            }
-            return next;
-          });
-        },
-      ),
-      listen<{
-        sessionId: string;
-        snippets: import("../types/vaultContextSearch").VaultSnippetRecord[];
-        meta: import("../types/vaultContextSearch").SearchWorkspaceContextMeta | null;
-        replyContextSources: ReplyContextSources;
-      }>("llm:context-ready", (e) => {
-        const { sessionId, snippets, meta, replyContextSources } = e.payload;
-        if (sessionId !== activeSessionRef.current) return;
-
-        if (snippets.length > 0 && meta) {
-          const paths = snippets.map((s) => s.relPath).join(", ");
-          const priv = snippets.filter((s) => s.kind === "privateOmitted").length;
-          let line = t("aiPanel.vaultLine", {
-            paths,
-            scannedFiles: meta.scannedFiles,
-            elapsedMs: meta.elapsedMs,
-          });
-          if (priv > 0) {
-            line += ` ${t("aiPanel.vaultPrivateOmitted", { count: priv })}`;
-          }
-          if (meta.stoppedEarly) {
-            line += ` ${t("aiPanel.vaultStoppedEarly")}`;
-          }
-          setVaultSearchSummary(line);
-        } else {
-          setVaultSearchSummary(null);
-        }
-
-        for (const s of snippets) {
-          if (s.kind !== "privateOmitted") {
-            sharedDocPathsRef.current.add(s.relPath);
-          }
-        }
-
-        setMessages((prev) => {
-          const idx = prev.findIndex((m) => m.role === "assistant" && m.streaming);
-          if (idx < 0) return prev;
-          const next = [...prev];
-          next[idx] = { ...next[idx], meta: { ...next[idx].meta, replyContextSources } };
-          return next;
-        });
-
-        setIsVaultSearching(false);
-      }),
-      // P2 Tool Calling Loop：Agent 轮次结束 → 最终化助手消息、清理 streaming 状态
-      listen<{ sessionId: string }>("llm:agent-done", (e) => {
-        const sid = e.payload.sessionId;
-        const skillMapping = skillSessionMapRef.current.get(sid);
-
-        // Skill 子轮次完成：优先处理，不依赖 activeSessionRef
-        if (skillMapping) {
-          skillSessionMapRef.current.delete(sid);
-          if (activeSessionRef.current === sid) {
-            activeSessionRef.current = parentSessionRef.current;
-          }
-          parentSessionRef.current = null;
-
-          setMessages((prev) =>
-            findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
-              ...tc,
-              skillStreaming: false,
-            })) ?? prev,
-          );
-          return;
-        }
-
-        // 其余情况：保持原有顶层 agent-done 逻辑
-        if (sid !== activeSessionRef.current) {
-          return;
-        }
-
-        // 顶层 agent 循环完成
-        markNeedPersist();
-        activeSessionRef.current = null;
-        isAgentModeRef.current = false;
-        setIsStreaming(false);
-        setIsVaultSearching(false);
-        setMessages((prev) => {
-          const next = [...prev];
-          const last = next[next.length - 1];
-          if (last?.role === "assistant" && last.streaming) {
-            next[next.length - 1] = {
-              ...last,
-              streaming: false,
-              meta: last.meta?.timing
-                ? { ...last.meta, timing: { ...last.meta.timing, endMs: Date.now() } }
-                : last.meta,
-            };
-          }
-          const strippedPack = stripMarkedPassiveHighlightWithCount(next);
-          if (strippedPack.stripped > 0) {
-            passiveHighlightMarkedCountRef.current = Math.max(
-              0,
-              passiveHighlightMarkedCountRef.current - strippedPack.stripped,
-            );
-          }
-          return strippedPack.messages;
-        });
-      }),
-    ]).then((unlisteners) => {
-      if (disposed) {
-        unlisteners.forEach((u) => void u());
-        return;
-      }
-      pending.push(...unlisteners);
+  const { activeSessionRef, isAgentModeRef, parentSessionRef, skillSessionMapRef } =
+    useAgentEventHandlers({
+      setMessages,
+      setIsStreaming,
+      setIsVaultSearching,
+      setErrorBanner,
+      setInput,
+      setVaultSearchSummary,
+      setInviteData,
+      setChallengeInlineData,
+      setMemoryProposals,
+      setProposalDecisions,
+      setActiveApproval,
+      composerInputRef,
+      messagesRef,
+      sharedDocPathsRef,
+      approvalQueueRef,
+      inviteSearchEpochRef,
+      lastSentQueryRef,
+      enoughForThisChatRef,
+      depthModeForInviteRef,
+      autoResolvedForInviteRef,
+      thoughtInviteExcludeRef,
+      passiveHighlightMarkedCountRef,
+      markNeedPersist,
+      attachCitationToLastAssistant,
+      freqCtrl,
+      conversationId,
+      t,
     });
 
-    return () => {
-      disposed = true;
-      pending.forEach((u) => void u());
-    };
-  }, [
-    markNeedPersist,
-    setMessages,
-    setIsStreaming,
-    freqCtrl,
-    t,
-    attachCitationToLastAssistant,
-    conversationId,
-  ]);
 
   useEffect(() => {
     if (!isTauri()) return;
@@ -2064,178 +1407,23 @@ export function AiConversationPanel() {
           </p>
         ) : (
           messages.map((m) => (
-            <div
+            <MessageBubble
               key={m.id}
-              className={`ai-chat__row ai-chat__row--${m.role}`}
-              {...dragExcludeProps}
-            >
-              <div className={`ai-chat__bubble ai-chat__bubble--${m.role}`}>
-                {m.role === "assistant" ? (
-                  <>
-                    {m.meta?.toolCalls && m.meta.toolCalls.length > 0 ? (
-                      <div className="ai-chat__tool-calls">
-                        {m.meta.toolCalls.map((tc) => (
-                          <details key={tc.toolCallId} className="ai-chat__tool-call-details">
-                            <summary className={`ai-chat__tool-call ai-chat__tool-call--${tc.status}`}>
-                              <span className="ai-chat__tool-call__icon" aria-hidden={true}>
-                                {tc.status === "running" ? "⋯" : tc.status === "done" ? "✓" : "✗"}
-                              </span>
-                              <span className="ai-chat__tool-call__name">{tc.displaySummary || tc.toolName}</span>
-                              {tc.durationMs != null && (
-                                <span className="ai-chat__tool-call__duration">
-                                  {(tc.durationMs / 1000).toFixed(1)}s
-                                </span>
-                              )}
-                            </summary>
-                            <div className="ai-chat__tool-call__detail">
-                              {tc.inputSummary && (
-                                <div className="ai-chat__tool-call__input">
-                                  <span className="ai-chat__tool-call__label">输入</span>
-                                  <code>{tc.inputSummary}</code>
-                                </div>
-                              )}
-                              {tc.skillId && (
-                                <div className="ai-chat__skill-inline">
-                                  <span className="ai-chat__skill-badge">🧠 {tc.skillName}</span>
-                                  <AiAssistantMarkdown content={tc.skillContent || ""} />
-                                  {tc.skillStreaming && <span className="ai-chat__typing">▌</span>}
-                                  {tc.skillToolCalls && tc.skillToolCalls.length > 0 && (
-                                    <div className="ai-chat__tool-calls">
-                                      {tc.skillToolCalls.map((stc) => (
-                                        <details key={stc.toolCallId} className="ai-chat__tool-call-details">
-                                          <summary className={`ai-chat__tool-call ai-chat__tool-call--${stc.status}`}>
-                                            <span className="ai-chat__tool-call__icon" aria-hidden={true}>
-                                              {stc.status === "running" ? "⋯" : stc.status === "done" ? "✓" : "✗"}
-                                            </span>
-                                            <span className="ai-chat__tool-call__name">{stc.displaySummary || stc.toolName}</span>
-                                            {stc.durationMs != null && (
-                                              <span className="ai-chat__tool-call__duration">
-                                                {(stc.durationMs / 1000).toFixed(1)}s
-                                              </span>
-                                            )}
-                                          </summary>
-                                          <div className="ai-chat__tool-call__detail">
-                                            {stc.inputSummary && (
-                                              <div className="ai-chat__tool-call__input">
-                                                <span className="ai-chat__tool-call__label">输入</span>
-                                                <code>{stc.inputSummary}</code>
-                                              </div>
-                                            )}
-                                            {stc.resultSummary && (
-                                              <div className="ai-chat__tool-call__result">
-                                                <span className="ai-chat__tool-call__label">结果</span>
-                                                <code>{stc.resultSummary}</code>
-                                              </div>
-                                            )}
-                                            {stc.errorMessage && (
-                                              <div className="ai-chat__tool-call__error">
-                                                <span className="ai-chat__tool-call__label">错误</span>
-                                                <code>{stc.errorMessage}</code>
-                                              </div>
-                                            )}
-                                          </div>
-                                        </details>
-                                      ))}
-                                    </div>
-                                  )}
-                                </div>
-                              )}
-                              {tc.resultSummary && (
-                                <div className="ai-chat__tool-call__result">
-                                  <span className="ai-chat__tool-call__label">结果</span>
-                                  <code>{tc.resultSummary}</code>
-                                </div>
-                              )}
-                              {tc.errorMessage && (
-                                <div className="ai-chat__tool-call__error">
-                                  <span className="ai-chat__tool-call__label">错误</span>
-                                  <code>{tc.errorMessage}</code>
-                                </div>
-                              )}
-                            </div>
-                          </details>
-                        ))}
-                      </div>
-                    ) : null}
-                    {m.meta?.budgetWarning && (
-                      <div className="ai-chat__budget-warning">
-                        Agent {m.meta.budgetWarning.used}/{m.meta.budgetWarning.limit} tool calls used
-                      </div>
-                    )}
-                    <AiAssistantMarkdown content={m.content} />
-                    {!m.streaming && m.meta?.thoughtCitation && !m.meta.thoughtCitation.privateOmitted ? (
-                      <button
-                        type="button"
-                        className="ai-chat__thought-cite"
-                        onClick={() => openMarkdownTab?.(m.meta!.thoughtCitation!.relPath)}
-                        {...dragExcludeProps}
-                      >
-                        {t("aiPanel.thoughtCited", {
-                          note:
-                            m.meta.thoughtCitation.relPath.split("/").pop() ??
-                            m.meta.thoughtCitation.relPath,
-                        })}
-                      </button>
-                    ) : null}
-                    {!m.streaming && m.meta?.replyContextSources && hasReplyContextSourcesToShow(m.meta.replyContextSources) ? (
-                      <AiReplyContextSources sources={m.meta.replyContextSources} onOpenMarkdown={openMarkdownTab} />
-                    ) : null}
-                    {m.streaming ? (
-                      <span className="ai-chat__typing" aria-hidden={true}>
-                        ▌
-                      </span>
-                    ) : null}
-                    {!m.streaming && m.content.trim().length > 0 ? (
-                      <>
-                        <button
-                          type="button"
-                          className="ai-chat__copy"
-                          onClick={() => void copyAssistant(m.content)}
-                          aria-label={t("aiPanel.copyAria")}
-                          title={t("aiPanel.copyMd")}
-                          {...dragExcludeProps}
-                        >
-                          <IconCopyClipboard />
-                        </button>
-                        <button
-                          type="button"
-                          className="ai-chat__copy"
-                          onClick={() => {
-                            setSavePopoverVariant("default");
-                            setSavePopoverUserMsgId(null);
-                            setSavePopoverContent(m.content);
-                            setSavePopoverMsgId(m.id);
-                          }}
-                          aria-label={t("thoughtSave.buttonTitle")}
-                          title={t("thoughtSave.buttonTitle")}
-                          {...dragExcludeProps}
-                        >
-                          <IconSaveThought />
-                        </button>
-                      </>
-                    ) : null}
-                    {m.meta?.timing ? (
-                      <StreamingTimer timing={m.meta.timing} streaming={!!m.streaming} modelName={m.meta.modelName} />
-                    ) : null}
-                  </>
-                ) : (
-                  <div className="ai-chat__user-stack">
-                    <p className="ai-chat__user-text">{m.content}</p>
-                    {m.meta?.passiveHighlight?.phase === "marked" ? (
-                      <PassiveHighlightSaveCue
-                        t={t}
-                        state={m.meta.passiveHighlight as PassiveHighlightMarked}
-                        disabled={!!savePopoverMsgId}
-                        onSaveClick={() => {
-                          // 落库用用户原文：detect 的 summary 易为英文，与中文输入下「保存想法」预期不符
-                          openPassiveHighlightSave(m.id, m.content);
-                        }}
-                      />
-                    ) : null}
-                  </div>
-                )}
-              </div>
-            </div>
+              message={m}
+              onCopy={copyAssistant}
+              onSaveAsThought={(msgId, content) => {
+                setSavePopoverVariant("default");
+                setSavePopoverUserMsgId(null);
+                setSavePopoverContent(content);
+                setSavePopoverMsgId(msgId);
+              }}
+              onOpenThoughtCite={openMarkdownTab}
+              savePopoverMsgId={savePopoverMsgId}
+              onPassiveHighlightSave={openPassiveHighlightSave}
+              t={t}
+              dragExcludeProps={dragExcludeProps}
+              hasReplyContextSourcesToShow={hasReplyContextSourcesToShow}
+            />
           ))
         )}
 
diff --git a/src/components/MessageBubble.tsx b/src/components/MessageBubble.tsx
new file mode 100644
index 0000000..020fed0
--- /dev/null
+++ b/src/components/MessageBubble.tsx
@@ -0,0 +1,160 @@
+import type { TFunction } from "i18next";
+import type { ChatMessage } from "../hooks/useWorkspaceAiConversations";
+import type { ReplyContextSources } from "../types/replyContextSources";
+import type { PassiveHighlightMarked } from "../types/passiveHighlight";
+import { ToolCallItem } from "./ToolCallItem";
+import { AiAssistantMarkdown } from "./AiAssistantMarkdown";
+import { StreamingTimer } from "./StreamingTimer";
+import { PassiveHighlightSaveCue } from "./PassiveHighlightSaveCue";
+import { AiReplyContextSources } from "./AiReplyContextSources";
+
+function IconCopyClipboard() {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden={true}
+    >
+      <rect width="14" height="14" x="8" y="8" rx="2" ry="2" />
+      <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
+    </svg>
+  );
+}
+
+export function IconSaveThought() {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden={true}
+    >
+      <path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z" />
+    </svg>
+  );
+}
+
+type MessageBubbleProps = {
+  message: ChatMessage;
+  onCopy: (content: string) => void;
+  onSaveAsThought: (msgId: string, content: string) => void;
+  onOpenThoughtCite: ((relPath: string) => void) | undefined;
+  savePopoverMsgId: string | null;
+  onPassiveHighlightSave: (msgId: string, content: string) => void;
+  t: TFunction;
+  dragExcludeProps: Record<string, unknown>;
+  hasReplyContextSourcesToShow: (sources: ReplyContextSources) => boolean;
+};
+
+export function MessageBubble({
+  message: m,
+  onCopy,
+  onSaveAsThought,
+  onOpenThoughtCite,
+  savePopoverMsgId,
+  onPassiveHighlightSave,
+  t,
+  dragExcludeProps,
+  hasReplyContextSourcesToShow,
+}: MessageBubbleProps) {
+  return (
+    <div
+      className={`ai-chat__row ai-chat__row--${m.role}`}
+      {...dragExcludeProps}
+    >
+      <div className={`ai-chat__bubble ai-chat__bubble--${m.role}`}>
+        {m.role === "assistant" ? (
+          <>
+            {m.meta?.toolCalls && m.meta.toolCalls.length > 0 ? (
+              <div className="ai-chat__tool-calls">
+                {m.meta.toolCalls.map((tc) => (
+                  <ToolCallItem key={tc.toolCallId} tc={tc} />
+                ))}
+              </div>
+            ) : null}
+            {m.meta?.budgetWarning && (
+              <div className="ai-chat__budget-warning">
+                Agent {m.meta.budgetWarning.used}/{m.meta.budgetWarning.limit} tool calls used
+              </div>
+            )}
+            <AiAssistantMarkdown content={m.content} />
+            {!m.streaming && m.meta?.thoughtCitation && !m.meta.thoughtCitation.privateOmitted ? (
+              <button
+                type="button"
+                className="ai-chat__thought-cite"
+                onClick={() => onOpenThoughtCite?.(m.meta!.thoughtCitation!.relPath)}
+                {...dragExcludeProps}
+              >
+                {t("aiPanel.thoughtCited", {
+                  note:
+                    m.meta.thoughtCitation.relPath.split("/").pop() ??
+                    m.meta.thoughtCitation.relPath,
+                })}
+              </button>
+            ) : null}
+            {!m.streaming && m.meta?.replyContextSources && hasReplyContextSourcesToShow(m.meta.replyContextSources) ? (
+              <AiReplyContextSources sources={m.meta.replyContextSources} onOpenMarkdown={onOpenThoughtCite} />
+            ) : null}
+            {m.streaming ? (
+              <span className="ai-chat__typing" aria-hidden={true}>
+                ▌
+              </span>
+            ) : null}
+            {!m.streaming && m.content.trim().length > 0 ? (
+              <>
+                <button
+                  type="button"
+                  className="ai-chat__copy"
+                  onClick={() => void onCopy(m.content)}
+                  aria-label={t("aiPanel.copyAria")}
+                  title={t("aiPanel.copyMd")}
+                  {...dragExcludeProps}
+                >
+                  <IconCopyClipboard />
+                </button>
+                <button
+                  type="button"
+                  className="ai-chat__copy"
+                  onClick={() => onSaveAsThought(m.id, m.content)}
+                  aria-label={t("thoughtSave.buttonTitle")}
+                  title={t("thoughtSave.buttonTitle")}
+                  {...dragExcludeProps}
+                >
+                  <IconSaveThought />
+                </button>
+              </>
+            ) : null}
+            {m.meta?.timing ? (
+              <StreamingTimer timing={m.meta.timing} streaming={!!m.streaming} modelName={m.meta.modelName} />
+            ) : null}
+          </>
+        ) : (
+          <div className="ai-chat__user-stack">
+            <p className="ai-chat__user-text">{m.content}</p>
+            {m.meta?.passiveHighlight?.phase === "marked" ? (
+              <PassiveHighlightSaveCue
+                t={t}
+                state={m.meta.passiveHighlight as PassiveHighlightMarked}
+                disabled={!!savePopoverMsgId}
+                onSaveClick={() => {
+                  onPassiveHighlightSave(m.id, m.content);
+                }}
+              />
+            ) : null}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/ToolCallItem.tsx b/src/components/ToolCallItem.tsx
new file mode 100644
index 0000000..f98319b
--- /dev/null
+++ b/src/components/ToolCallItem.tsx
@@ -0,0 +1,54 @@
+import type { ToolCallDisplayInfo } from "../hooks/useWorkspaceAiConversations";
+import { AiAssistantMarkdown } from "./AiAssistantMarkdown";
+
+export function ToolCallItem({ tc }: { tc: ToolCallDisplayInfo }) {
+  return (
+    <details className="ai-chat__tool-call-details">
+      <summary className={`ai-chat__tool-call ai-chat__tool-call--${tc.status}`}>
+        <span className="ai-chat__tool-call__icon" aria-hidden={true}>
+          {tc.status === "running" ? "⋯" : tc.status === "done" ? "✓" : "✗"}
+        </span>
+        <span className="ai-chat__tool-call__name">{tc.displaySummary || tc.toolName}</span>
+        {tc.durationMs != null && (
+          <span className="ai-chat__tool-call__duration">
+            {(tc.durationMs / 1000).toFixed(1)}s
+          </span>
+        )}
+      </summary>
+      <div className="ai-chat__tool-call__detail">
+        {tc.inputSummary && (
+          <div className="ai-chat__tool-call__input">
+            <span className="ai-chat__tool-call__label">输入</span>
+            <code>{tc.inputSummary}</code>
+          </div>
+        )}
+        {tc.skillId && (
+          <div className="ai-chat__skill-inline">
+            <span className="ai-chat__skill-badge">🧠 {tc.skillName}</span>
+            <AiAssistantMarkdown content={tc.skillContent || ""} />
+            {tc.skillStreaming && <span className="ai-chat__typing">▌</span>}
+            {tc.skillToolCalls && tc.skillToolCalls.length > 0 && (
+              <div className="ai-chat__tool-calls">
+                {tc.skillToolCalls.map((stc) => (
+                  <ToolCallItem key={stc.toolCallId} tc={stc} />
+                ))}
+              </div>
+            )}
+          </div>
+        )}
+        {tc.resultSummary && (
+          <div className="ai-chat__tool-call__result">
+            <span className="ai-chat__tool-call__label">结果</span>
+            <code>{tc.resultSummary}</code>
+          </div>
+        )}
+        {tc.errorMessage && (
+          <div className="ai-chat__tool-call__error">
+            <span className="ai-chat__tool-call__label">错误</span>
+            <code>{tc.errorMessage}</code>
+          </div>
+        )}
+      </div>
+    </details>
+  );
+}
diff --git a/src/hooks/useAgentEventHandlers.ts b/src/hooks/useAgentEventHandlers.ts
new file mode 100644
index 0000000..6349907
--- /dev/null
+++ b/src/hooks/useAgentEventHandlers.ts
@@ -0,0 +1,734 @@
+import { type MutableRefObject, useRef, useEffect } from "react";
+import { isTauri } from "@tauri-apps/api/core";
+import { listen, type UnlistenFn } from "@tauri-apps/api/event";
+import { invoke } from "@tauri-apps/api/core";
+import type { ChatMessage, ToolCallDisplayInfo } from "./useWorkspaceAiConversations";
+import type { ReplyContextSources } from "../types/replyContextSources";
+import type { ApprovalRequest } from "../types/toolTypes";
+import type { AutoResolvedDepth, DepthMode, ThoughtRetrievalResult, CountVaultThoughtsForReviewResponse, GenerateChallengeQuestionResponse } from "../types/cognitiveTypes";
+import type { VaultConfigForUi } from "../types/vaultAiConfig";
+import { isChallengeInlineLlmReady } from "../utils/isChallengeReviewLlmReady";
+import { stripMarkedPassiveHighlightWithCount } from "../utils/passiveHighlightLifecycle";
+import { trackKnowforgeEvent } from "../utils/knowforgeAnalytics";
+import { getAppLocale } from "../i18n";
+import type { TFunction } from "i18next";
+import type { CognitiveFrequencyControl } from "./useCognitiveFrequencyControl";
+
+// ---------------------------------------------------------------------------
+// Helper functions (exported for use by handleStop in AiConversationPanel)
+// ---------------------------------------------------------------------------
+
+export function retractInterruptedTurn(prev: ChatMessage[]): ChatMessage[] {
+  const next = [...prev];
+  const last = next[next.length - 1];
+  if (last?.role === "assistant" && last.streaming) {
+    next.pop();
+  }
+  const u = next[next.length - 1];
+  if (u?.role === "user") {
+    next.pop();
+  }
+  return next;
+}
+
+export function finalizeStreamingAssistant(prev: ChatMessage[]): ChatMessage[] {
+  const next = [...prev];
+  const last = next[next.length - 1];
+  if (last?.role === "assistant" && last.streaming) {
+    next[next.length - 1] = { ...last, streaming: false };
+  }
+  return next;
+}
+
+export function findAndPatchToolCall(
+  prev: ChatMessage[],
+  targetToolCallId: string,
+  patcher: (tc: ToolCallDisplayInfo) => ToolCallDisplayInfo,
+): ChatMessage[] | null {
+  for (let i = prev.length - 1; i >= 0; i--) {
+    const m = prev[i];
+    if (m.role !== "assistant") continue;
+
+    const tcs = m.meta?.toolCalls;
+    if (tcs) {
+      const tcIdx = tcs.findIndex((tc) => tc.toolCallId === targetToolCallId);
+      if (tcIdx !== -1) {
+        const next = [...prev];
+        const updated = [...tcs];
+        updated[tcIdx] = patcher(updated[tcIdx]);
+        next[i] = { ...m, meta: { ...m.meta, toolCalls: updated } };
+        return next;
+      }
+    }
+  }
+  return null;
+}
+
+export function mergeStreamDelta(current: string, delta: string): string {
+  if (!delta) return current;
+  if (!current) return delta;
+  if (current.endsWith(delta)) return current;
+  if (delta.startsWith(current)) return delta;
+
+  const maxOverlap = Math.min(current.length, delta.length);
+  for (let overlap = maxOverlap; overlap > 0; overlap -= 1) {
+    if (current.endsWith(delta.slice(0, overlap))) {
+      return current + delta.slice(overlap);
+    }
+  }
+  return current + delta;
+}
+
+// ---------------------------------------------------------------------------
+// Types used inside event listeners but not exported by other files
+// ---------------------------------------------------------------------------
+
+type MemoryProposalBatch = {
+  session_id: string;
+  proposals: Array<{
+    id: string;
+    action: string;
+    category: string;
+    target: string | null;
+    content: unknown;
+    reason: string;
+  }>;
+  created_at: string;
+};
+
+type InviteData = { thought: ThoughtRetrievalResult | null; question: string };
+
+type ChallengeInlineData = {
+  thought: ThoughtRetrievalResult;
+  question: string;
+  templateKind: string;
+};
+
+type VaultCfgForSend = VaultConfigForUi;
+
+// ---------------------------------------------------------------------------
+// Hook deps & return types
+// ---------------------------------------------------------------------------
+
+export type AgentEventDeps = {
+  setMessages: React.Dispatch<React.SetStateAction<ChatMessage[]>>;
+  setIsStreaming: (v: boolean) => void;
+  setIsVaultSearching: (v: boolean) => void;
+  setErrorBanner: (v: string | null) => void;
+  setInput: (v: string) => void;
+  setVaultSearchSummary: (v: string | null) => void;
+
+  setInviteData: (v: InviteData | null) => void;
+  setChallengeInlineData: (v: ChallengeInlineData | null) => void;
+  setMemoryProposals: (v: MemoryProposalBatch | null) => void;
+  setProposalDecisions: (v: Record<string, boolean>) => void;
+  setActiveApproval: React.Dispatch<React.SetStateAction<ApprovalRequest | null>>;
+
+  composerInputRef: MutableRefObject<string>;
+  messagesRef: MutableRefObject<ChatMessage[]>;
+  sharedDocPathsRef: MutableRefObject<Set<string>>;
+  approvalQueueRef: MutableRefObject<ApprovalRequest[]>;
+  inviteSearchEpochRef: MutableRefObject<number>;
+  lastSentQueryRef: MutableRefObject<string>;
+  enoughForThisChatRef: MutableRefObject<boolean>;
+  depthModeForInviteRef: MutableRefObject<DepthMode>;
+  autoResolvedForInviteRef: MutableRefObject<AutoResolvedDepth | null>;
+  thoughtInviteExcludeRef: MutableRefObject<string[]>;
+  passiveHighlightMarkedCountRef: MutableRefObject<number>;
+
+  markNeedPersist: () => void;
+  attachCitationToLastAssistant: (citation: ThoughtRetrievalResult | null) => void;
+  freqCtrl: CognitiveFrequencyControl;
+  conversationId: string | null;
+  t: TFunction;
+};
+
+export type AgentSessionState = {
+  activeSessionRef: MutableRefObject<string | null>;
+  isAgentModeRef: MutableRefObject<boolean>;
+  parentSessionRef: MutableRefObject<string | null>;
+  skillSessionMapRef: MutableRefObject<Map<string, { parentToolCallId: string }>>;
+};
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
+  const activeSessionRef = useRef<string | null>(null);
+  const isAgentModeRef = useRef(false);
+  const parentSessionRef = useRef<string | null>(null);
+  const skillSessionMapRef = useRef<Map<string, { parentToolCallId: string }>>(new Map());
+
+  const {
+    setMessages,
+    setIsStreaming,
+    setIsVaultSearching,
+    setErrorBanner,
+    setInput,
+    setVaultSearchSummary,
+    setInviteData,
+    setChallengeInlineData,
+    setMemoryProposals,
+    setProposalDecisions,
+    setActiveApproval,
+    composerInputRef,
+    messagesRef,
+    sharedDocPathsRef,
+    approvalQueueRef,
+    inviteSearchEpochRef,
+    lastSentQueryRef,
+    enoughForThisChatRef,
+    depthModeForInviteRef,
+    autoResolvedForInviteRef,
+    thoughtInviteExcludeRef,
+    passiveHighlightMarkedCountRef,
+    markNeedPersist,
+    attachCitationToLastAssistant,
+    freqCtrl,
+    conversationId,
+    t,
+  } = deps;
+
+  useEffect(() => {
+    if (!isTauri()) {
+      return;
+    }
+
+    let disposed = false;
+    const pending: UnlistenFn[] = [];
+
+    void Promise.all([
+      listen<{ sessionId: string; delta: string }>("llm:stream-chunk", (e) => {
+        const p = e.payload;
+        if (p.sessionId !== activeSessionRef.current) {
+          return;
+        }
+        const skillMapping = skillSessionMapRef.current.get(p.sessionId);
+        if (skillMapping) {
+          setMessages((prev) =>
+            findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+              ...tc,
+              skillContent: (tc.skillContent || "") + p.delta,
+            })) ?? prev,
+          );
+          return;
+        }
+        setMessages((prev) => {
+          let next = [...prev];
+          const last = next[next.length - 1];
+          if (last?.role === "assistant" && last.streaming) {
+            const isFirstToken = last.content === "";
+            next[next.length - 1] = {
+              ...last,
+              content: mergeStreamDelta(last.content, p.delta),
+              meta: isFirstToken && last.meta?.timing
+                ? { ...last.meta, timing: { ...last.meta.timing, firstTokenMs: Date.now() } }
+                : last.meta,
+            };
+          }
+          return next;
+        });
+      }),
+      listen<{ sessionId: string }>("llm:stream-done", (e) => {
+        const p = e.payload;
+        if (p.sessionId !== activeSessionRef.current) {
+          return;
+        }
+        setIsVaultSearching(false);
+        if (isAgentModeRef.current) {
+          return;
+        }
+        markNeedPersist();
+        activeSessionRef.current = null;
+        setIsStreaming(false);
+        setMessages((prev) => {
+          const next = [...prev];
+          const last = next[next.length - 1];
+          if (last?.role === "assistant" && last.streaming) {
+            next[next.length - 1] = {
+              ...last,
+              streaming: false,
+              meta: last.meta?.timing
+                ? { ...last.meta, timing: { ...last.meta.timing, endMs: Date.now() } }
+                : last.meta,
+            };
+          }
+          const strippedPack = stripMarkedPassiveHighlightWithCount(next);
+          if (strippedPack.stripped > 0) {
+            passiveHighlightMarkedCountRef.current = Math.max(
+              0,
+              passiveHighlightMarkedCountRef.current - strippedPack.stripped,
+            );
+          }
+          return strippedPack.messages;
+        });
+
+        const epoch = ++inviteSearchEpochRef.current;
+        setInviteData(null);
+        setChallengeInlineData(null);
+        const query = lastSentQueryRef.current.trim();
+        if (!query || enoughForThisChatRef.current) return;
+        const dm = depthModeForInviteRef.current;
+        const ar = autoResolvedForInviteRef.current;
+        if (dm === "shallow" || (dm === "auto" && ar === "shallow")) {
+          return;
+        }
+        void (async () => {
+          try {
+            type SearchResp = {
+              thought: ThoughtRetrievalResult | null;
+              thoughts?: ThoughtRetrievalResult[];
+              meta: { scannedFiles: number; stoppedEarly: boolean; elapsedMs: number };
+            };
+
+            const turnIdx = messagesRef.current.filter((m) => m.role === "user").length;
+            const inviteEligible = freqCtrl.shouldShowInvite(
+              dm,
+              enoughForThisChatRef.current,
+              turnIdx,
+              ar,
+            );
+
+            if (inviteEligible) {
+              const resp = await invoke<SearchResp>("search_thought_for_invite", {
+                args: {
+                  query,
+                  excludeRelPaths: thoughtInviteExcludeRef.current,
+                  maxResults: 1,
+                },
+              });
+              if (inviteSearchEpochRef.current !== epoch || disposed) return;
+              const excerptRaw = resp.thought?.excerpt;
+              const question =
+                excerptRaw && excerptRaw.length > 0
+                  ? t("invite.thoughtQuestion", {
+                      excerpt:
+                        excerptRaw.length > 60 ? `${excerptRaw.slice(0, 60)}...` : excerptRaw,
+                    })
+                  : t("invite.defaultQuestion");
+              setInviteData({ thought: resp.thought, question });
+              attachCitationToLastAssistant(resp.thought ?? null);
+              const th = resp.thought;
+              if (
+                th &&
+                !th.privateOmitted &&
+                th.thoughtId &&
+                isTauri() &&
+                th.relPath
+              ) {
+                void invoke("append_ai_thought_reference", {
+                  args: {
+                    relPath: th.relPath,
+                    thoughtId: th.thoughtId,
+                    context: query.slice(0, 2000),
+                    relevance: "ai-conversation-invite",
+                  },
+                }).catch(() => {});
+              }
+              return;
+            }
+
+            let cfg: VaultCfgForSend;
+            try {
+              cfg = await invoke<VaultCfgForSend>("get_vault_config_for_ui");
+            } catch {
+              return;
+            }
+            if (inviteSearchEpochRef.current !== epoch || disposed) return;
+            if (!isChallengeInlineLlmReady(cfg as VaultConfigForUi)) return;
+
+            const countResp = await invoke<CountVaultThoughtsForReviewResponse>(
+              "count_vault_thoughts_for_review",
+            );
+            if (inviteSearchEpochRef.current !== epoch || disposed) return;
+            const total = countResp.totalThoughts;
+            if (
+              !freqCtrl.shouldShowChallengeInline(dm, ar, {
+                inviteWillShow: false,
+                thoughtId: null,
+                vaultThoughtTotal: total,
+              })
+            ) {
+              return;
+            }
+
+            const respMany = await invoke<SearchResp>("search_thought_for_invite", {
+              args: {
+                query,
+                excludeRelPaths: thoughtInviteExcludeRef.current,
+                maxResults: 3,
+              },
+            });
+            if (inviteSearchEpochRef.current !== epoch || disposed) return;
+            const pick =
+              respMany.thoughts?.find((x) => x.excerpt && !x.privateOmitted) ?? respMany.thought;
+            if (!pick?.excerpt || pick.privateOmitted) return;
+
+            const gen = await invoke<GenerateChallengeQuestionResponse>("generate_challenge_question", {
+              args: {
+                thoughtExcerpt: pick.excerpt,
+                relPath: pick.relPath,
+                conversationQuery: query,
+                depthMode: dm,
+                uiLocale: getAppLocale(),
+              },
+            });
+            if (inviteSearchEpochRef.current !== epoch || disposed) return;
+            if (gen.shouldSkip || !gen.question.trim()) return;
+
+            void freqCtrl.recordChallengeInlineShown(pick.thoughtId);
+            void trackKnowforgeEvent("review.inline_shown", {
+              thoughtId: pick.thoughtId,
+              templateKind: gen.templateKind,
+            });
+            setChallengeInlineData({
+              thought: pick,
+              question: gen.question,
+              templateKind: gen.templateKind,
+            });
+            attachCitationToLastAssistant(pick);
+            if (!pick.privateOmitted && pick.thoughtId && isTauri()) {
+              void invoke("append_ai_thought_reference", {
+                args: {
+                  relPath: pick.relPath,
+                  thoughtId: pick.thoughtId,
+                  context: query.slice(0, 2000),
+                  relevance: "ai-challenge-inline",
+                },
+              }).catch(() => {});
+            }
+          } catch {
+            // timeout or other failure: silently skip
+          }
+        })();
+      }),
+      listen<{ sessionId: string; code?: string; message: string }>("llm:stream-error", (e) => {
+        const p = e.payload;
+        if (p.sessionId !== activeSessionRef.current) {
+          return;
+        }
+        if (parentSessionRef.current) {
+          const parent = parentSessionRef.current;
+          parentSessionRef.current = null;
+          activeSessionRef.current = parent;
+          setMessages((prev) => {
+            const next = [...prev];
+            const last = next[next.length - 1];
+            if (last?.role === "assistant" && last.streaming) {
+              next[next.length - 1] = { ...last, streaming: false };
+            }
+            return next;
+          });
+          return;
+        }
+        markNeedPersist();
+        activeSessionRef.current = null;
+        isAgentModeRef.current = false;
+        setIsStreaming(false);
+        setIsVaultSearching(false);
+        if (p.code === "cancelled") {
+          setMessages((prev) => {
+            if (composerInputRef.current.trim().length > 0) {
+              return finalizeStreamingAssistant(prev);
+            }
+            let lastUser = "";
+            for (let i = prev.length - 1; i >= 0; i--) {
+              if (prev[i].role === "user") {
+                lastUser = prev[i].content;
+                break;
+              }
+            }
+            const next = retractInterruptedTurn(prev);
+            if (lastUser.length > 0) {
+              queueMicrotask(() => setInput(lastUser));
+            }
+            return next;
+          });
+          return;
+        }
+        setMessages((prev) => {
+          const next = [...prev];
+          const last = next[next.length - 1];
+          if (last?.role === "assistant" && last.streaming) {
+            next[next.length - 1] = { ...last, streaming: false };
+          }
+          const strippedPack = stripMarkedPassiveHighlightWithCount(next);
+          if (strippedPack.stripped > 0) {
+            passiveHighlightMarkedCountRef.current = Math.max(
+              0,
+              passiveHighlightMarkedCountRef.current - strippedPack.stripped,
+            );
+          }
+          return strippedPack.messages;
+        });
+        setErrorBanner(p.message);
+      }),
+      listen<{ sessionId: string; toolCallId: string; toolName: string; inputSummary?: string; displaySummary?: string }>(
+        "llm:tool-call-start",
+        (e) => {
+          const p = e.payload;
+          if (p.sessionId !== activeSessionRef.current) {
+            return;
+          }
+          const skillMapping = skillSessionMapRef.current.get(p.sessionId);
+          const newCall: ToolCallDisplayInfo = {
+            toolCallId: p.toolCallId,
+            toolName: p.toolName,
+            displaySummary: p.displaySummary || undefined,
+            status: "running",
+            inputSummary: p.inputSummary,
+          };
+          if (skillMapping) {
+            setMessages((prev) =>
+              findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+                ...tc,
+                skillToolCalls: [...(tc.skillToolCalls || []), newCall],
+              })) ?? prev,
+            );
+            return;
+          }
+          setMessages((prev) => {
+            const next = [...prev];
+            const last = next[next.length - 1];
+            if (last?.role !== "assistant") return prev;
+            const existing = last.meta?.toolCalls ?? [];
+            return [
+              ...next.slice(0, -1),
+              {
+                ...last,
+                meta: { ...last.meta, toolCalls: [...existing, newCall] },
+              },
+            ];
+          });
+        },
+      ),
+      listen<{ sessionId: string; toolCallId: string; success: boolean; resultSummary?: string; durationMs?: number; errorMessage?: string }>(
+        "llm:tool-call-done",
+        (e) => {
+          const p = e.payload;
+          if (p.sessionId !== activeSessionRef.current) {
+            return;
+          }
+          const skillMapping = skillSessionMapRef.current.get(p.sessionId);
+          if (skillMapping) {
+            setMessages((prev) =>
+              findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+                ...tc,
+                skillToolCalls: (tc.skillToolCalls || []).map((stc) =>
+                  stc.toolCallId === p.toolCallId
+                    ? { ...stc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
+                    : stc,
+                ),
+              })) ?? prev,
+            );
+            return;
+          }
+          setMessages((prev) => {
+            const patchTc = (tc: ToolCallDisplayInfo): ToolCallDisplayInfo =>
+              tc.toolCallId === p.toolCallId
+                ? { ...tc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
+                : tc;
+
+            for (let i = prev.length - 1; i >= 0; i -= 1) {
+              const m = prev[i];
+              if (m.role !== "assistant") continue;
+
+              if (m.meta?.toolCalls?.some((tc) => tc.toolCallId === p.toolCallId)) {
+                const next = [...prev];
+                next[i] = { ...m, meta: { ...m.meta, toolCalls: m.meta.toolCalls!.map(patchTc) } };
+                return next;
+              }
+            }
+            return prev;
+          });
+        },
+      ),
+      listen<ApprovalRequest>("llm:tool-approval-request", (e) => {
+        const p = e.payload;
+        if (p.sessionId !== activeSessionRef.current) {
+          return;
+        }
+        setActiveApproval((cur) => {
+          if (cur === null) {
+            return p;
+          }
+          approvalQueueRef.current.push(p);
+          return cur;
+        });
+      }),
+      listen<MemoryProposalBatch>("llm:memory-proposals", (e) => {
+        if (e.payload.session_id === activeSessionRef.current) {
+          setMemoryProposals(e.payload);
+          setProposalDecisions({});
+        }
+      }),
+      listen<{
+        sessionId: string;
+        conversationId: string;
+        skillId: string;
+        skillName: string;
+        parentToolCallId: string;
+      }>("llm:skill-spawn", (e) => {
+        const p = e.payload;
+        if (!activeSessionRef.current || activeSessionRef.current === p.sessionId) {
+          return;
+        }
+        if (conversationId && p.conversationId !== conversationId) {
+          return;
+        }
+        parentSessionRef.current = activeSessionRef.current;
+        activeSessionRef.current = p.sessionId;
+        skillSessionMapRef.current.set(p.sessionId, {
+          parentToolCallId: p.parentToolCallId,
+        });
+        setMessages((prev) =>
+          findAndPatchToolCall(prev, p.parentToolCallId, (tc) => ({
+            ...tc,
+            skillId: p.skillId,
+            skillName: p.skillName,
+            skillContent: "",
+            skillToolCalls: [],
+            skillStreaming: true,
+          })) ?? prev,
+        );
+      }),
+      listen<{ sessionId: string; used: number; limit: number; type: string }>(
+        "llm:budget-warning",
+        (e) => {
+          if (e.payload.sessionId !== activeSessionRef.current) return;
+          setMessages((prev) => {
+            const next = [...prev];
+            const last = next[next.length - 1];
+            if (last?.role === "assistant") {
+              next[next.length - 1] = {
+                ...last,
+                meta: {
+                  ...last.meta,
+                  budgetWarning: { used: e.payload.used, limit: e.payload.limit },
+                },
+              };
+            }
+            return next;
+          });
+        },
+      ),
+      listen<{
+        sessionId: string;
+        snippets: import("../types/vaultContextSearch").VaultSnippetRecord[];
+        meta: import("../types/vaultContextSearch").SearchWorkspaceContextMeta | null;
+        replyContextSources: ReplyContextSources;
+      }>("llm:context-ready", (e) => {
+        const { sessionId, snippets, meta, replyContextSources } = e.payload;
+        if (sessionId !== activeSessionRef.current) return;
+
+        if (snippets.length > 0 && meta) {
+          const paths = snippets.map((s) => s.relPath).join(", ");
+          const priv = snippets.filter((s) => s.kind === "privateOmitted").length;
+          let line = t("aiPanel.vaultLine", {
+            paths,
+            scannedFiles: meta.scannedFiles,
+            elapsedMs: meta.elapsedMs,
+          });
+          if (priv > 0) {
+            line += ` ${t("aiPanel.vaultPrivateOmitted", { count: priv })}`;
+          }
+          if (meta.stoppedEarly) {
+            line += ` ${t("aiPanel.vaultStoppedEarly")}`;
+          }
+          setVaultSearchSummary(line);
+        } else {
+          setVaultSearchSummary(null);
+        }
+
+        for (const s of snippets) {
+          if (s.kind !== "privateOmitted") {
+            sharedDocPathsRef.current.add(s.relPath);
+          }
+        }
+
+        setMessages((prev) => {
+          const idx = prev.findIndex((m) => m.role === "assistant" && m.streaming);
+          if (idx < 0) return prev;
+          const next = [...prev];
+          next[idx] = { ...next[idx], meta: { ...next[idx].meta, replyContextSources } };
+          return next;
+        });
+
+        setIsVaultSearching(false);
+      }),
+      listen<{ sessionId: string }>("llm:agent-done", (e) => {
+        const sid = e.payload.sessionId;
+        const skillMapping = skillSessionMapRef.current.get(sid);
+
+        if (skillMapping) {
+          skillSessionMapRef.current.delete(sid);
+          if (activeSessionRef.current === sid) {
+            activeSessionRef.current = parentSessionRef.current;
+          }
+          parentSessionRef.current = null;
+
+          setMessages((prev) =>
+            findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+              ...tc,
+              skillStreaming: false,
+            })) ?? prev,
+          );
+          return;
+        }
+
+        if (sid !== activeSessionRef.current) {
+          return;
+        }
+
+        markNeedPersist();
+        activeSessionRef.current = null;
+        isAgentModeRef.current = false;
+        setIsStreaming(false);
+        setIsVaultSearching(false);
+        setMessages((prev) => {
+          const next = [...prev];
+          const last = next[next.length - 1];
+          if (last?.role === "assistant" && last.streaming) {
+            next[next.length - 1] = {
+              ...last,
+              streaming: false,
+              meta: last.meta?.timing
+                ? { ...last.meta, timing: { ...last.meta.timing, endMs: Date.now() } }
+                : last.meta,
+            };
+          }
+          const strippedPack = stripMarkedPassiveHighlightWithCount(next);
+          if (strippedPack.stripped > 0) {
+            passiveHighlightMarkedCountRef.current = Math.max(
+              0,
+              passiveHighlightMarkedCountRef.current - strippedPack.stripped,
+            );
+          }
+          return strippedPack.messages;
+        });
+      }),
+    ]).then((unlisteners) => {
+      if (disposed) {
+        unlisteners.forEach((u) => void u());
+        return;
+      }
+      pending.push(...unlisteners);
+    });
+
+    return () => {
+      disposed = true;
+      pending.forEach((u) => void u());
+    };
+  }, [
+    markNeedPersist,
+    setMessages,
+    setIsStreaming,
+    freqCtrl,
+    t,
+    attachCitationToLastAssistant,
+    conversationId,
+  ]);
+
+  return { activeSessionRef, isAgentModeRef, parentSessionRef, skillSessionMapRef };
+}

From e80b420d75b50144f2989ebb9c4c56c4129746ac Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Fri, 3 Jul 2026 17:37:36 +0800
Subject: [PATCH 07/10] docs: add CLAUDE.md with file size limits and code
 placement rules

Co-authored-by: Claude (Opus 4.6) <noreply@anthropic.com>
---
 CLAUDE.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..eacb328
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,42 @@
+# KnowForge Project Guidelines
+
+## Build & Test
+
+```bash
+# Frontend type check
+npx tsc --noEmit
+
+# Backend tests
+cargo test --manifest-path src-tauri/Cargo.toml
+
+# Dev server
+npm run dev
+```
+
+## Architecture: File Size Limits
+
+Single-file components and modules must not grow unboundedly. Hard limits (lines):
+
+| Threshold | Action |
+|-----------|--------|
+| > 800     | Consider extracting hooks or sub-components |
+| > 1200    | Must extract before adding new logic |
+| > 1800    | Treat as a bug — refactor before any other work |
+
+Current large files that must NOT grow further without extraction:
+
+- `src/App.tsx` (1921) — route/layout only; new features go in dedicated components
+- `src/components/AiConversationPanel.tsx` (1758) — recently refactored; new event handlers → `useAgentEventHandlers`, new rendering → `MessageBubble` or new sub-component, new UI state → dedicated hook
+- `src/components/AiLlmSettingsModal.tsx` (1680) — extract section components for new settings
+- `src/hooks/useOpenDocs.ts` (1140) — extract sub-hooks for new doc operations
+- `src-tauri/src/lib.rs` (1828) — Tauri command hub; new commands register here but implementation goes in domain modules
+- `src-tauri/src/llm/agent_loop.rs` (1581) — core loop; new tool handling → tool modules, new context logic → context_guard
+
+### Where to put new code
+
+- New Tauri event listener → `src/hooks/useAgentEventHandlers.ts`
+- New message rendering logic → `src/components/MessageBubble.tsx` or a new `src/components/<Name>.tsx`
+- New tool call display → `src/components/ToolCallItem.tsx`
+- New React hook → `src/hooks/use<Name>.ts`
+- New Rust tool → `src-tauri/src/tools/built_in/<name>.rs`
+- New LLM feature → `src-tauri/src/llm/<name>.rs`, not inline in `agent_loop.rs`

From e449ef6fd1d4246da819bfdebaea3fa9d1b5abca Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Mon, 6 Jul 2026 11:24:50 +0800
Subject: [PATCH 08/10] fix(events): add heartbeat, idempotent handlers, and
 event buffer for reliability

Co-authored-by: Claude (Opus 4.6) <noreply@anthropic.com>
---
 src-tauri/src/llm/agent_loop.rs    |  24 ++-
 src/hooks/useAgentEventHandlers.ts | 290 +++++++++++++++++++++++++----
 2 files changed, 275 insertions(+), 39 deletions(-)

diff --git a/src-tauri/src/llm/agent_loop.rs b/src-tauri/src/llm/agent_loop.rs
index 665bb36..93f3d1e 100644
--- a/src-tauri/src/llm/agent_loop.rs
+++ b/src-tauri/src/llm/agent_loop.rs
@@ -230,6 +230,7 @@ pub async fn run_agent_stream(
 
     loop {
         iteration += 1;
+        emit_heartbeat(&app, &session_id, iteration);
         let est_tokens: usize = messages.iter().map(|m| m.content.len() / 3).sum();
         eprintln!(
             "[agent_loop] session={} iter={} msgs={} est_tokens={} tool_calls_so_far={}/{}",
@@ -377,7 +378,7 @@ pub async fn run_agent_stream(
 
         // 5. 并行执行工具（跳过循环调用；每个工具有独立超时，支持取消）
         let default_tool_timeout = Duration::from_millis(config.timeout_ms);
-        let results = join_all(normalized_calls.iter().enumerate().map(|(idx, tc)| {
+        let results_fut = join_all(normalized_calls.iter().enumerate().map(|(idx, tc)| {
             let skip = looped.get(idx).copied().unwrap_or(false);
             let cancel = cancel.clone();
             let registry = registry.clone();
@@ -446,8 +447,18 @@ pub async fn run_agent_stream(
                 let duration_ms = exec_start.elapsed().as_millis() as u64;
                 (result, duration_ms)
             }
-        }))
-        .await;
+        }));
+        tokio::pin!(results_fut);
+        let mut heartbeat_interval = tokio::time::interval(Duration::from_secs(10));
+        heartbeat_interval.tick().await;
+        let results = loop {
+            tokio::select! {
+                r = &mut results_fut => break r,
+                _ = heartbeat_interval.tick() => {
+                    emit_heartbeat(&app, &session_id, iteration);
+                }
+            }
+        };
 
         for (i, tc) in normalized_calls.iter().enumerate() {
             if let Some((result, duration_ms)) = results.get(i) {
@@ -1005,6 +1016,13 @@ fn emit_agent_done(app: &AppHandle, session_id: &str) {
     );
 }
 
+fn emit_heartbeat(app: &AppHandle, session_id: &str, loop_iteration: u32) {
+    let _ = app.emit(
+        "llm:heartbeat",
+        json!({ "sessionId": session_id, "loopIteration": loop_iteration }),
+    );
+}
+
 /// Truncate a string to `max_len` bytes, appending "..." if truncated.
 /// Respects Unicode character boundaries.
 fn truncate_str(s: &str, max_len: usize) -> String {
diff --git a/src/hooks/useAgentEventHandlers.ts b/src/hooks/useAgentEventHandlers.ts
index 6349907..51bed6c 100644
--- a/src/hooks/useAgentEventHandlers.ts
+++ b/src/hooks/useAgentEventHandlers.ts
@@ -198,20 +198,201 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
     let disposed = false;
     const pending: UnlistenFn[] = [];
 
+    const WATCHDOG_TIMEOUT_MS = 30_000;
+    let watchdogTimer: ReturnType<typeof setTimeout> | null = null;
+
+    function resetWatchdog() {
+      if (watchdogTimer) clearTimeout(watchdogTimer);
+      watchdogTimer = setTimeout(() => {
+        activeSessionRef.current = null;
+        isAgentModeRef.current = false;
+        parentSessionRef.current = null;
+        setIsStreaming(false);
+        setMessages((prev) => finalizeStreamingAssistant(prev));
+        setErrorBanner("连接超时，请重试");
+      }, WATCHDOG_TIMEOUT_MS);
+    }
+
+    function clearWatchdog() {
+      if (watchdogTimer) {
+        clearTimeout(watchdogTimer);
+        watchdogTimer = null;
+      }
+    }
+
+    // --- Event buffer: holds events whose prerequisites haven't arrived yet ---
+    type PendingEvent = { type: string; payload: unknown; receivedAt: number };
+    const pendingEvents = new Map<string, PendingEvent[]>();
+    const BUFFER_TIMEOUT_MS = 30_000;
+
+    function bufferEvent(waitKey: string, type: string, payload: unknown) {
+      const queue = pendingEvents.get(waitKey) || [];
+      queue.push({ type, payload, receivedAt: Date.now() });
+      pendingEvents.set(waitKey, queue);
+    }
+
+    function drainBuffer(waitKey: string): PendingEvent[] {
+      const queue = pendingEvents.get(waitKey);
+      if (!queue?.length) return [];
+      pendingEvents.delete(waitKey);
+      const now = Date.now();
+      return queue.filter((ev) => {
+        if (now - ev.receivedAt > BUFFER_TIMEOUT_MS) {
+          console.warn(`[event-buffer] dropped stale ${ev.type} for key=${waitKey}`);
+          return false;
+        }
+        return true;
+      });
+    }
+
+    function applyBufferedToolCallEvent(msgs: ChatMessage[], ev: PendingEvent): ChatMessage[] {
+      const p = ev.payload as Record<string, unknown>;
+      switch (ev.type) {
+        case "tool-call-done": {
+          const toolCallId = p.toolCallId as string;
+          const success = p.success as boolean;
+          for (let i = msgs.length - 1; i >= 0; i--) {
+            const m = msgs[i];
+            if (m.role !== "assistant") continue;
+            if (m.meta?.toolCalls?.some((tc) => tc.toolCallId === toolCallId)) {
+              const next = [...msgs];
+              next[i] = {
+                ...m,
+                meta: {
+                  ...m.meta,
+                  toolCalls: m.meta!.toolCalls!.map((tc) => {
+                    if (tc.toolCallId !== toolCallId) return tc;
+                    if (tc.status === "done" || tc.status === "error") return tc;
+                    return { ...tc, status: (success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary as string | undefined, durationMs: p.durationMs as number | undefined, errorMessage: p.errorMessage as string | undefined };
+                  }),
+                },
+              };
+              return next;
+            }
+          }
+          return msgs;
+        }
+        case "tool-call-done-skill": {
+          const parentToolCallId = p._parentToolCallId as string;
+          const toolCallId = p.toolCallId as string;
+          const success = p.success as boolean;
+          return findAndPatchToolCall(msgs, parentToolCallId, (tc) => ({
+            ...tc,
+            skillToolCalls: (tc.skillToolCalls || []).map((stc) =>
+              stc.toolCallId === toolCallId
+                ? (stc.status === "done" || stc.status === "error") ? stc : { ...stc, status: (success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary as string | undefined, durationMs: p.durationMs as number | undefined, errorMessage: p.errorMessage as string | undefined }
+                : stc,
+            ),
+          })) ?? msgs;
+        }
+        case "stream-chunk-skill": {
+          const parentToolCallId = p._parentToolCallId as string;
+          const delta = p.delta as string;
+          return findAndPatchToolCall(msgs, parentToolCallId, (tc) => ({
+            ...tc,
+            skillContent: (tc.skillContent || "") + delta,
+          })) ?? msgs;
+        }
+        case "tool-call-start-skill": {
+          const parentToolCallId = p._parentToolCallId as string;
+          const newCall = p._newCall as ToolCallDisplayInfo;
+          return findAndPatchToolCall(msgs, parentToolCallId, (tc) => {
+            if (tc.skillToolCalls?.some((stc) => stc.toolCallId === newCall.toolCallId)) return tc;
+            return { ...tc, skillToolCalls: [...(tc.skillToolCalls || []), newCall] };
+          }) ?? msgs;
+        }
+        case "skill-spawn": {
+          const parentToolCallId = p.parentToolCallId as string;
+          return findAndPatchToolCall(msgs, parentToolCallId, (tc) => {
+            if (tc.skillId) return tc;
+            return { ...tc, skillId: p.skillId as string, skillName: p.skillName as string, skillContent: "", skillToolCalls: [], skillStreaming: true };
+          }) ?? msgs;
+        }
+        case "agent-done-skill": {
+          const parentToolCallId = p._parentToolCallId as string;
+          return findAndPatchToolCall(msgs, parentToolCallId, (tc) => ({
+            ...tc,
+            skillStreaming: false,
+          })) ?? msgs;
+        }
+        default:
+          return msgs;
+      }
+    }
+
+    function flushToolCallBuffer(msgs: ChatMessage[], toolCallId: string): ChatMessage[] {
+      const events = drainBuffer(toolCallId);
+      let current = msgs;
+      for (const ev of events) {
+        current = applyBufferedToolCallEvent(current, ev);
+      }
+      return current;
+    }
+
+    function applyBufferedAssistantEvent(msgs: ChatMessage[], ev: PendingEvent): ChatMessage[] {
+      const p = ev.payload as Record<string, unknown>;
+      switch (ev.type) {
+        case "tool-call-start": {
+          const next = [...msgs];
+          const last = next[next.length - 1];
+          if (last?.role !== "assistant") return msgs;
+          const existing = last.meta?.toolCalls ?? [];
+          const toolCallId = p.toolCallId as string;
+          if (existing.some((tc) => tc.toolCallId === toolCallId)) return msgs;
+          const newCall: ToolCallDisplayInfo = {
+            toolCallId,
+            toolName: p.toolName as string,
+            displaySummary: (p.displaySummary as string) || undefined,
+            status: "running",
+            inputSummary: p.inputSummary as string | undefined,
+          };
+          let result: ChatMessage[] = [
+            ...next.slice(0, -1),
+            { ...last, meta: { ...last.meta, toolCalls: [...existing, newCall] } },
+          ];
+          result = flushToolCallBuffer(result, toolCallId);
+          return result;
+        }
+        case "context-ready": {
+          const replyContextSources = p.replyContextSources as ReplyContextSources;
+          const idx = msgs.findIndex((m) => m.role === "assistant" && m.streaming);
+          if (idx < 0) return msgs;
+          const next = [...msgs];
+          next[idx] = { ...next[idx], meta: { ...next[idx].meta, replyContextSources } };
+          return next;
+        }
+        default:
+          return msgs;
+      }
+    }
+
+    function flushAssistantBuffer(msgs: ChatMessage[]): ChatMessage[] {
+      const events = drainBuffer("assistant-msg");
+      let current = msgs;
+      for (const ev of events) {
+        current = applyBufferedAssistantEvent(current, ev);
+      }
+      return current;
+    }
+
     void Promise.all([
       listen<{ sessionId: string; delta: string }>("llm:stream-chunk", (e) => {
         const p = e.payload;
         if (p.sessionId !== activeSessionRef.current) {
           return;
         }
+        resetWatchdog();
         const skillMapping = skillSessionMapRef.current.get(p.sessionId);
         if (skillMapping) {
-          setMessages((prev) =>
-            findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+          setMessages((prev) => {
+            const patched = findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
               ...tc,
               skillContent: (tc.skillContent || "") + p.delta,
-            })) ?? prev,
-          );
+            }));
+            if (patched) return patched;
+            bufferEvent(skillMapping.parentToolCallId, "stream-chunk-skill", { ...p, _parentToolCallId: skillMapping.parentToolCallId });
+            return prev;
+          });
           return;
         }
         setMessages((prev) => {
@@ -226,6 +407,7 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
                 ? { ...last.meta, timing: { ...last.meta.timing, firstTokenMs: Date.now() } }
                 : last.meta,
             };
+            if (isFirstToken) return flushAssistantBuffer(next);
           }
           return next;
         });
@@ -235,6 +417,7 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
         if (p.sessionId !== activeSessionRef.current) {
           return;
         }
+        clearWatchdog();
         setIsVaultSearching(false);
         if (isAgentModeRef.current) {
           return;
@@ -408,6 +591,7 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
         if (p.sessionId !== activeSessionRef.current) {
           return;
         }
+        clearWatchdog();
         if (parentSessionRef.current) {
           const parent = parentSessionRef.current;
           parentSessionRef.current = null;
@@ -471,6 +655,7 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
           if (p.sessionId !== activeSessionRef.current) {
             return;
           }
+          resetWatchdog();
           const skillMapping = skillSessionMapRef.current.get(p.sessionId);
           const newCall: ToolCallDisplayInfo = {
             toolCallId: p.toolCallId,
@@ -480,26 +665,35 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
             inputSummary: p.inputSummary,
           };
           if (skillMapping) {
-            setMessages((prev) =>
-              findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
-                ...tc,
-                skillToolCalls: [...(tc.skillToolCalls || []), newCall],
-              })) ?? prev,
-            );
+            setMessages((prev) => {
+              const patched = findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => {
+                if (tc.skillToolCalls?.some((stc) => stc.toolCallId === p.toolCallId)) return tc;
+                return { ...tc, skillToolCalls: [...(tc.skillToolCalls || []), newCall] };
+              });
+              if (patched) return flushToolCallBuffer(patched, p.toolCallId);
+              bufferEvent(skillMapping.parentToolCallId, "tool-call-start-skill", { ...p, _parentToolCallId: skillMapping.parentToolCallId, _newCall: newCall });
+              return prev;
+            });
             return;
           }
           setMessages((prev) => {
             const next = [...prev];
             const last = next[next.length - 1];
-            if (last?.role !== "assistant") return prev;
+            if (last?.role !== "assistant") {
+              bufferEvent("assistant-msg", "tool-call-start", p);
+              return prev;
+            }
             const existing = last.meta?.toolCalls ?? [];
-            return [
+            if (existing.some((tc) => tc.toolCallId === p.toolCallId)) return prev;
+            let result: ChatMessage[] = [
               ...next.slice(0, -1),
               {
                 ...last,
                 meta: { ...last.meta, toolCalls: [...existing, newCall] },
               },
             ];
+            result = flushToolCallBuffer(result, p.toolCallId);
+            return result;
           });
         },
       ),
@@ -510,25 +704,30 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
           if (p.sessionId !== activeSessionRef.current) {
             return;
           }
+          resetWatchdog();
           const skillMapping = skillSessionMapRef.current.get(p.sessionId);
           if (skillMapping) {
-            setMessages((prev) =>
-              findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+            setMessages((prev) => {
+              const patched = findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
                 ...tc,
                 skillToolCalls: (tc.skillToolCalls || []).map((stc) =>
                   stc.toolCallId === p.toolCallId
-                    ? { ...stc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
+                    ? (stc.status === "done" || stc.status === "error") ? stc : { ...stc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
                     : stc,
                 ),
-              })) ?? prev,
-            );
+              }));
+              if (patched) return patched;
+              bufferEvent(skillMapping.parentToolCallId, "tool-call-done-skill", { ...p, _parentToolCallId: skillMapping.parentToolCallId });
+              return prev;
+            });
             return;
           }
           setMessages((prev) => {
-            const patchTc = (tc: ToolCallDisplayInfo): ToolCallDisplayInfo =>
-              tc.toolCallId === p.toolCallId
-                ? { ...tc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage }
-                : tc;
+            const patchTc = (tc: ToolCallDisplayInfo): ToolCallDisplayInfo => {
+              if (tc.toolCallId !== p.toolCallId) return tc;
+              if (tc.status === "done" || tc.status === "error") return tc;
+              return { ...tc, status: (p.success ? "done" : "error") as ToolCallDisplayInfo["status"], resultSummary: p.resultSummary, durationMs: p.durationMs, errorMessage: p.errorMessage };
+            };
 
             for (let i = prev.length - 1; i >= 0; i -= 1) {
               const m = prev[i];
@@ -540,6 +739,7 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
                 return next;
               }
             }
+            bufferEvent(p.toolCallId, "tool-call-done", p);
             return prev;
           });
         },
@@ -549,6 +749,7 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
         if (p.sessionId !== activeSessionRef.current) {
           return;
         }
+        resetWatchdog();
         setActiveApproval((cur) => {
           if (cur === null) {
             return p;
@@ -577,26 +778,27 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
         if (conversationId && p.conversationId !== conversationId) {
           return;
         }
+        resetWatchdog();
         parentSessionRef.current = activeSessionRef.current;
         activeSessionRef.current = p.sessionId;
         skillSessionMapRef.current.set(p.sessionId, {
           parentToolCallId: p.parentToolCallId,
         });
-        setMessages((prev) =>
-          findAndPatchToolCall(prev, p.parentToolCallId, (tc) => ({
-            ...tc,
-            skillId: p.skillId,
-            skillName: p.skillName,
-            skillContent: "",
-            skillToolCalls: [],
-            skillStreaming: true,
-          })) ?? prev,
-        );
+        setMessages((prev) => {
+          const patched = findAndPatchToolCall(prev, p.parentToolCallId, (tc) => {
+            if (tc.skillId) return tc;
+            return { ...tc, skillId: p.skillId, skillName: p.skillName, skillContent: "", skillToolCalls: [], skillStreaming: true };
+          });
+          if (patched) return patched;
+          bufferEvent(p.parentToolCallId, "skill-spawn", p);
+          return prev;
+        });
       }),
       listen<{ sessionId: string; used: number; limit: number; type: string }>(
         "llm:budget-warning",
         (e) => {
           if (e.payload.sessionId !== activeSessionRef.current) return;
+          resetWatchdog();
           setMessages((prev) => {
             const next = [...prev];
             const last = next[next.length - 1];
@@ -621,6 +823,7 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
       }>("llm:context-ready", (e) => {
         const { sessionId, snippets, meta, replyContextSources } = e.payload;
         if (sessionId !== activeSessionRef.current) return;
+        resetWatchdog();
 
         if (snippets.length > 0 && meta) {
           const paths = snippets.map((s) => s.relPath).join(", ");
@@ -649,7 +852,10 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
 
         setMessages((prev) => {
           const idx = prev.findIndex((m) => m.role === "assistant" && m.streaming);
-          if (idx < 0) return prev;
+          if (idx < 0) {
+            bufferEvent("assistant-msg", "context-ready", { replyContextSources });
+            return prev;
+          }
           const next = [...prev];
           next[idx] = { ...next[idx], meta: { ...next[idx].meta, replyContextSources } };
           return next;
@@ -659,6 +865,7 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
       }),
       listen<{ sessionId: string }>("llm:agent-done", (e) => {
         const sid = e.payload.sessionId;
+        clearWatchdog();
         const skillMapping = skillSessionMapRef.current.get(sid);
 
         if (skillMapping) {
@@ -668,12 +875,15 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
           }
           parentSessionRef.current = null;
 
-          setMessages((prev) =>
-            findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
+          setMessages((prev) => {
+            const patched = findAndPatchToolCall(prev, skillMapping.parentToolCallId, (tc) => ({
               ...tc,
               skillStreaming: false,
-            })) ?? prev,
-          );
+            }));
+            if (patched) return patched;
+            bufferEvent(skillMapping.parentToolCallId, "agent-done-skill", { _parentToolCallId: skillMapping.parentToolCallId });
+            return prev;
+          });
           return;
         }
 
@@ -708,6 +918,12 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
           return strippedPack.messages;
         });
       }),
+      listen<{ sessionId: string; loopIteration: number }>("llm:heartbeat", (e) => {
+        const p = e.payload;
+        if (p.sessionId !== activeSessionRef.current &&
+            p.sessionId !== parentSessionRef.current) return;
+        resetWatchdog();
+      }),
     ]).then((unlisteners) => {
       if (disposed) {
         unlisteners.forEach((u) => void u());
@@ -718,6 +934,8 @@ export function useAgentEventHandlers(deps: AgentEventDeps): AgentSessionState {
 
     return () => {
       disposed = true;
+      clearWatchdog();
+      pendingEvents.clear();
       pending.forEach((u) => void u());
     };
   }, [

From 549a00440e84d9cc7870546ed46cd3ea9c32460d Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Mon, 6 Jul 2026 11:25:03 +0800
Subject: [PATCH 09/10] fix(ui): show memory content in proposal cards

Co-authored-by: Claude (Opus 4.6) <noreply@anthropic.com>
---
 src/components/AiConversationPanel.tsx |  5 +++++
 src/components/MemoryProposals.css     | 19 +++++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/src/components/AiConversationPanel.tsx b/src/components/AiConversationPanel.tsx
index c895d58..1dcb7ae 100644
--- a/src/components/AiConversationPanel.tsx
+++ b/src/components/AiConversationPanel.tsx
@@ -1527,6 +1527,11 @@ export function AiConversationPanel() {
                       <span className="memory-proposals__target">{p.target}</span>
                     )}
                   </div>
+                  {p.content != null && (
+                    <pre className="memory-proposals__content">
+                      {typeof p.content === "string" ? p.content : JSON.stringify(p.content, null, 2)}
+                    </pre>
+                  )}
                   <p className="memory-proposals__reason">{p.reason}</p>
                   <div className="memory-proposals__buttons">
                     <button
diff --git a/src/components/MemoryProposals.css b/src/components/MemoryProposals.css
index 15b8ce5..3301376 100644
--- a/src/components/MemoryProposals.css
+++ b/src/components/MemoryProposals.css
@@ -68,6 +68,20 @@
   color: var(--crepe-color-on-surface-variant, #6b7280);
 }
 
+.memory-proposals__content {
+  font-size: 0.78rem;
+  color: var(--crepe-color-on-surface-variant, #6b7280);
+  margin: 4px 0 6px;
+  padding: 6px 8px;
+  border-radius: 4px;
+  background: color-mix(in srgb, var(--crepe-color-surface, #fff), transparent 20%);
+  white-space: pre-wrap;
+  word-break: break-word;
+  line-height: 1.4;
+  max-height: 120px;
+  overflow-y: auto;
+}
+
 .memory-proposals__reason {
   font-size: 0.82rem;
   color: var(--crepe-color-on-surface, #374151);
@@ -144,6 +158,11 @@
     background: color-mix(in srgb, var(--crepe-color-surface, #1f1f23), transparent 40%);
   }
 
+  .memory-proposals__content {
+    background: color-mix(in srgb, var(--crepe-color-surface, #1f1f23), transparent 20%);
+    color: var(--crepe-color-on-surface-variant, #a1a1aa);
+  }
+
   .memory-proposals__reason {
     color: var(--crepe-color-on-surface, #e4e4e7);
   }

From db93f0fd4815f0dda97ca8b21809d024233c6071 Mon Sep 17 00:00:00 2001
From: donfaquir <1458918806@qq.com>
Date: Mon, 6 Jul 2026 16:04:18 +0800
Subject: [PATCH 10/10] chore(release): bump version to 0.7.4

Co-authored-by: Claude (Opus 4.6) <noreply@anthropic.com>
---
 CHANGELOG.md              | 17 +++++++++
 package.json              |  2 +-
 plan/INDEX.md             | 76 +++++++++++++++++++++++++++++++++++++++
 src-tauri/Cargo.lock      |  2 +-
 src-tauri/Cargo.toml      |  2 +-
 src-tauri/tauri.conf.json |  2 +-
 6 files changed, 97 insertions(+), 4 deletions(-)
 create mode 100644 plan/INDEX.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d98d383..f8116e2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.7.4] - 2026-07-06
+
+### Added
+- 后端心跳事件（`llm:heartbeat`），agent loop 迭代及工具执行期间每 10 秒发送
+- 前端 watchdog 定时器，30 秒无事件自动恢复 streaming 状态
+- 事件缓冲队列：前置事件未到时缓冲后续事件，前置满足后自动冲刷
+- 记忆提案卡片展示完整 content 字段（之前仅显示推荐原因）
+
+### Changed
+- Planning 模式从 Phase A/B 两阶段简化为单次 agent loop 执行
+- AiConversationPanel 拆分：提取 ToolCallItem、MessageBubble 组件和 useAgentEventHandlers hook（-31%）
+
+### Fixed
+- 事件处理器幂等化：tool-call-start / skill-spawn / tool-call-done 防重复
+- context-guard 使用消息计数替代索引，避免快照漂移
+- 工具审批等待时间不再计入工具超时
+
 ## [0.7.3] - 2026-07-01
 
 ### Added
diff --git a/package.json b/package.json
index ab969dc..05b58df 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "knowforge",
   "private": true,
-  "version": "0.7.3",
+  "version": "0.7.4",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
diff --git a/plan/INDEX.md b/plan/INDEX.md
new file mode 100644
index 0000000..067437d
--- /dev/null
+++ b/plan/INDEX.md
@@ -0,0 +1,76 @@
+# Plan Index
+
+> 总控表：所有待办 spec 的状态、优先级一览。
+> 最后更新：2026-07-06
+
+---
+
+## Active
+
+（暂无进行中的 spec）
+
+---
+
+## Backlog
+
+（暂无 backlog — 当前架构已稳定，不再主动优化已知内部问题）
+
+---
+
+## Done
+
+| Spec | 优先级 | 完成日期 | 说明 |
+|------|--------|----------|------|
+| graph 私密节点过滤 | P0 | 2026-06-30 | 图谱泄漏私密笔记信息 |
+| note.read symlink 修复 | P0 | 2026-06-30 | 符号链接逃逸漏洞 |
+| link 隐私覆盖确认 | P1 | 2026-06-30 | link.suggest_related 隐私过滤 |
+| [thought.read](_archive/202506-tool-gap/spec-thought-read.md) | P0 | 2026-07-01 | 想法全文读取工具 |
+| [网络瞬态重试](_archive/202506-agent-loop-enhance/spec-error-recovery.md) | P1 | 2026-07-01 | 指数退避 + cancel 感知重试 |
+| [目标稳定性](_archive/202507-backlog-cleanup/goal-stability/README.md) | P1 | 2026-07-01 | 目标提取钉住 + 漂移警告 |
+| [计划审批](_archive/202507-backlog-cleanup/spec-plan-approval.md) | P1 | 2026-07-02 | Phase A→B 审批门（后已合并为单阶段） |
+| [主动压缩](_archive/202507-backlog-cleanup/spec-proactive-compaction.md) | P2 | 2026-07-03 | 修复快照索引漂移 |
+| Planning 模式简化 | P1 | 2026-07-03 | Phase A/B 合并为单次执行 |
+| God Component 拆分 | P1 | 2026-07-03 | AiConversationPanel 2570→1758 行 |
+| [事件可靠性](_archive/fix-event-reliability/) | P1 | 2026-07-06 | 心跳 + watchdog + 幂等 + 缓冲队列 |
+| 动态预算 | P1 | 已落地 | max_tool_calls 25 + budget 耗尽优雅降级 |
+| Agent Memory v2 | P1 | 已落地 | MemoryManager + agent_memory.json + LLM 提取 |
+
+---
+
+## Closed (Won't Fix)
+
+以下问题经评估后决定不修复，原因见括号：
+
+- D-2 隐式状态机（watchdog + 幂等 + 缓冲已从事件层面解决状态不一致）
+- D-4 会话重连（桌面应用刷新概率极低，审批超时已兜底）
+- D-6 压缩层边界不清（功能正确，重构风险 > 收益）
+- D-7 Skill 隔离（vault 非敌对数据，资源消耗已有界）
+- D-8 参数过多（纯美观，不影响功能）
+- 消息优先级（128K context 下几乎不触发）
+- 搜索重排序（LLM 本身是更强的 reranker）
+- 深度研究 / 工作记忆 / 结构化追踪 / 会话回放 / 并行 Agent / 零配置搜索 / MCP / 子 Agent / 思考可视化（关闭理由见 2026-07-03 评审）
+
+---
+
+## Archive
+
+历史计划文档已移至 `_archive/`，保留完整 git 历史。包含：
+
+- `iter1/` — 初始 AI 能力建设（P0-P5 工具 + agent loop）
+- `iter1-ai-upgrade/` — ContextGuard + 计划审查等 spec
+- `unified-provider/` — 统一 Provider 重构
+- `llm-latency/` — LLM 响应延迟优化
+- `agent-memory/` — Agent 记忆系统（20 个 spec）
+- `context-management-redesign/` — 上下文管理重设计（Phase 1 已完成）
+- `search-agent/` — 搜索 Agent 升级分析
+- `tool-gap-analysis/` — 工具缺口分析
+- `iter2-agent-evolution/` — Agent 架构进化路线（Phase 1-4）
+- `web-search-evolution/` — Web 搜索竞品分析与路线
+- `202506-security-privacy-fix/` — 安全与隐私修复（3 spec，全部完成）
+- `202506-tool-gap/` — 工具缺口（thought.read 完成，其余 wontfix）
+- `202506-agent-loop-enhance/` — Agent Loop 增强（重试已完成，反思循环 P3 延后）
+- `202507-backlog-cleanup/` — 2026-07 Backlog 清理
+- `fix-event-reliability/` — 事件可靠性三层修复（2026-07-06 完成）
+- `refactor-god-component/` — God Component 拆分方案
+- `review-agent-loop-architecture.md` — Agent Loop 架构评审
+- `session-context-management-analysis.md` — 会话上下文管理分析
diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock
index 7e91742..75012fe 100644
--- a/src-tauri/Cargo.lock
+++ b/src-tauri/Cargo.lock
@@ -2664,7 +2664,7 @@ dependencies = [
 
 [[package]]
 name = "knowforge"
-version = "0.7.3"
+version = "0.7.4"
 dependencies = [
  "aho-corasick",
  "async-trait",
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
index 2502b56..4b22715 100644
--- a/src-tauri/Cargo.toml
+++ b/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "knowforge"
-version = "0.7.3"
+version = "0.7.4"
 description = "Knowforge desktop app"
 authors = ["caichangqing"]
 edition = "2024"
diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json
index c9425e0..ffa9500 100644
--- a/src-tauri/tauri.conf.json
+++ b/src-tauri/tauri.conf.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Knowforge",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "identifier": "com.knowforge.desktop",
   "build": {
     "beforeDevCommand": "npm run dev",