Enhance tool documentation and add new features

- Added module-level documentation for memory tools (`remember`, `recall`, `forget`) to clarify their purpose.
- Improved documentation in `recall.rs` and `remember.rs` to describe the functionality and flow of memory entry operations.
- Updated `mod.rs` to include descriptions for the tool trait and execution context.
- Enhanced `plan.rs` with detailed comments on plan-mode signaling tools.
- Documented text search tools in `search.rs` to explain their functionality.
- Improved sequential-thinking tool documentation in `seqthink.rs`.
- Added safety filter documentation in `shell_filter` for credential and git operations.
- Enhanced utility tools documentation, including `cd`, `dir_cache_update`, and `todowrite`.
- Improved rendering documentation in view modules (`chat`, `markdown`, `status`, `workflow`) to clarify rendering flows and purposes.

src/app/state/runtime.rs

@@ -1,6 +1,11 @@
+//! Per-session runtime state: message history, pending tool queue,
+//! background bash jobs, lesson/review counters, and the `TurnEvent`
+//! stream emitted while an agent turn is in flight.
+
 use std::path::PathBuf;
 use serde::{Deserialize, Serialize};
 
+/// Cumulative token/latency counters for a session, persisted alongside it.
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, Default)]
 pub struct UsageStats {
     pub tokens_in: u64,
@@ -10,6 +15,9 @@ pub struct UsageStats {
     pub total_ms: u64,
 }
 
+/// Mutable, serializable state for one session: chat history, tool
+/// results, pending tools, background jobs, and lesson/review counters
+/// shown in the TUI status bar.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SessionRuntime {
     pub messages: Vec<crate::dto::chat::message::ChatMessage>,
@@ -36,6 +44,7 @@ pub struct SessionRuntime {
     pub usage: UsageStats,
 }
 
+/// Record of one completed tool invocation, kept for transcript/history.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolCallResult {
     pub tool_call_id: String,
@@ -45,6 +54,8 @@ pub struct ToolCallResult {
     pub duration_ms: u64,
 }
 
+/// A tool call awaiting execution, along with which execution model
+/// (inline, deferred, async) it should run under.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PendingTool {
     pub tool_name: String,
@@ -52,6 +63,8 @@ pub struct PendingTool {
     pub execution_model: crate::app::state::types::ExecutionModel,
 }
 
+/// Reference to a background bash job tracked in session state (the actual
+/// process handle lives elsewhere; this is just the display/status record).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct BashJobRef {
     pub id: String,
@@ -60,6 +73,8 @@ pub struct BashJobRef {
     pub running: bool,
 }
 
+/// Events emitted onto the turn-event queue while an agent turn runs,
+/// consumed by the event loop to update state and drive re-renders.
 #[derive(Debug, Clone)]
 pub enum TurnEvent {
     AssistantMessage(crate::dto::chat::message::ChatMessage),
@@ -86,6 +101,8 @@ pub enum TurnEvent {
 }
 
 impl SessionRuntime {
+    /// Create fresh runtime state for a session rooted at `session_dir`,
+    /// with all counters zeroed and `session_start` set to now.
     pub fn new(session_dir: PathBuf) -> Self {
         SessionRuntime {
             messages: Vec::new(),
@@ -113,6 +130,7 @@ impl SessionRuntime {
         }
     }
 
+    /// Append a message to the session's conversation history.
     pub fn push_message(&mut self, msg: crate::dto::chat::message::ChatMessage) {
         self.messages.push(msg);
     }