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/tool/utility/cd.rs

@@ -1,8 +1,11 @@
+//! `cd` tool: verify and resolve a workspace-relative directory path.
+
 use serde_json::{json, Value};
 use anyhow::{Result, anyhow};
 use super::super::Tool;
 use super::super::ToolCtx;
 
+/// Tool that resolves a workspace-relative path and reports whether it exists and is a dir.
 pub struct Cd;
 
 impl Tool for Cd {
@@ -27,6 +30,16 @@ impl Tool for Cd {
         })
     }
 
+    /// Resolve `path` against the workspace roots and report its status.
+    ///
+    /// Flow: extract `path` → `resolve_path` (sandboxed to `ctx.workspaces`) →
+    ///       check `exists()` and `is_dir()` → canonicalize → return canonical path.
+    ///
+    /// Why: the agent has no persistent cwd between tool calls; "cd" here is purely a
+    /// verification + canonicalization helper rather than a state change.
+    ///
+    /// Return: canonical path on success; explicit "does not exist" / "not a directory"
+    /// message (still `Ok`) so the model can react without treating it as an error.
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let rel = args.get("path")
             .and_then(|v| v.as_str())

src/tool/utility/dir_cache_update.rs

@@ -1,8 +1,19 @@
+//! Tool for refreshing the shared workspace directory cache.
+//!
+//! Flow: resolve the requested path against the workspace roots →
+//! non-recursively walk it → spin up a one-shot Tokio runtime (the agent
+//! turn runs on a plain `std::thread` with no async context) → write the
+//! entries into the shared `dir_cache` behind an async `RwLock`.
+//!
+//! Why: other tools rely on this cache for faster path resolution, so
+//! it must be kept fresh on demand rather than only populated at startup.
+
 use serde_json::{json, Value};
 use anyhow::{Result, anyhow};
 use super::super::Tool;
 use super::super::ToolCtx;
 
+/// Tool that refreshes the shared directory cache for a given path.
 pub struct DirCacheUpdate;
 
 impl Tool for DirCacheUpdate {
@@ -27,6 +38,19 @@ impl Tool for DirCacheUpdate {
         })
     }
 
+    /// Resolve `path`, walk its immediate entries, and store them in the shared cache.
+    ///
+    /// Flow: extract `path` argument → resolve against workspace roots →
+    /// bail early with a plain message (not an error) if it doesn't exist
+    /// → `walk_directory` collects direct children → spawn a temporary
+    /// Tokio runtime to acquire the async `RwLock` write guard and call
+    /// `cache.set(entries)`.
+    ///
+    /// Why: uses a fresh one-shot runtime instead of `ctx`'s own executor
+    /// because this tool can be invoked from a non-async thread.
+    ///
+    /// Return: a confirmation string with the entry count, or an error if
+    /// the `path` argument is missing or the temp runtime fails to start.
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let rel = args.get("path")
             .and_then(|v| v.as_str())
@@ -55,6 +79,14 @@ impl Tool for DirCacheUpdate {
     }
 }
 
+/// Non-recursively list the immediate entries of `path`.
+///
+/// Flow: read_dir → flatten Ok entries → collect their paths.
+///
+/// Why: silently skips unreadable entries (e.g. permission errors)
+/// rather than failing the whole cache update.
+///
+/// Return: paths of direct children; empty vec if `path` can't be read.
 fn walk_directory(path: &std::path::Path) -> Vec<std::path::PathBuf> {
     let mut result = Vec::new();
     if let Ok(entries) = std::fs::read_dir(path) {

src/tool/utility/dir_list.rs

@@ -1,9 +1,20 @@
+//! Tool for listing the immediate contents of a workspace directory.
+//!
+//! Flow: resolve the requested path against workspace roots → validate
+//! it exists and is a directory → read its direct children with
+//! `fs::read_dir`, tagging subdirectories with a trailing `/` → format
+//! into a header + newline-joined listing.
+//!
+//! Why: gives the agent a quick, one-level view of the workspace
+//! structure without pulling in the full recursive directory cache.
+
 use std::fs;
 use serde_json::{json, Value};
 use anyhow::{Result, anyhow};
 use super::super::Tool;
 use super::super::ToolCtx;
 
+/// Tool that lists the immediate contents of a workspace directory.
 pub struct DirList;
 
 impl Tool for DirList {
@@ -28,6 +39,19 @@ impl Tool for DirList {
         })
     }
 
+    /// List the immediate entries of the requested workspace directory.
+    ///
+    /// Flow: extract `path` argument → resolve against workspace roots →
+    /// short-circuit with a plain message if the path doesn't exist or
+    /// isn't a directory → `read_dir` → map each entry to its name
+    /// (appending `/` for subdirectories) → join into a formatted listing
+    /// with an entry-count header showing the canonicalized path.
+    ///
+    /// Why: entries whose metadata fails to read (`e.ok()` filter) are
+    /// silently skipped rather than aborting the whole listing.
+    ///
+    /// Return: header + newline-joined entry names, or an error if the
+    /// `path` argument is missing or `read_dir` fails outright.
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let rel = args.get("path")
             .and_then(|v| v.as_str())

src/tool/utility/mod.rs

@@ -1,3 +1,5 @@
+//! Small standalone utility tools (cd, dir listing/caching, pong, todowrite).
+
 pub mod cd;
 pub mod dir_cache_update;
 pub mod dir_list;

src/tool/utility/pong.rs

@@ -1,8 +1,17 @@
+//! Trivial connectivity-check tool.
+//!
+//! Flow: read the optional `message` argument → echo it back prefixed
+//! with `"pong: "`, defaulting to `"pong"` when no message is supplied.
+//!
+//! Why: gives callers a cheap, dependency-free way to verify the tool
+//! harness is reachable and responding before running real work.
+
 use serde_json::{json, Value};
 use anyhow::Result;
 use super::super::Tool;
 use super::super::ToolCtx;
 
+/// Tool that echoes back a message; used for connectivity/latency checks.
 pub struct Pong;
 
 impl Tool for Pong {

src/tool/utility/todowrite.rs

@@ -1,3 +1,13 @@
+//! Tool for appending timestamped tasks to the session's todo list.
+//!
+//! Flow: extract the `task` argument → format a Markdown checkbox line
+//! with a UTC timestamp → open `todo.md` in the session directory
+//! (creating it if needed) in append mode → write the line.
+//!
+//! Why: the file lives under `ctx.session_dir` so it persists per
+//! session and is picked up by the TUI's Todo panel; appending (rather
+//! than rewriting) keeps prior tasks intact.
+
 use std::fs;
 use std::path::PathBuf;
 use serde_json::{json, Value};
@@ -5,6 +15,7 @@ use anyhow::{Result, anyhow};
 use super::super::Tool;
 use super::super::ToolCtx;
 
+/// Tool that appends a timestamped task line to the session's todo.md.
 pub struct Todowrite;
 
 impl Tool for Todowrite {
@@ -29,6 +40,17 @@ impl Tool for Todowrite {
         })
     }
 
+    /// Append a timestamped, unchecked task line to the session's `todo.md`.
+    ///
+    /// Flow: extract `task` argument → build `- [ ] <task> (<timestamp>)`
+    /// line with a UTC `%Y-%m-%d %H:%M:%S` timestamp → open (create if
+    /// missing) `<session_dir>/todo.md` in append mode → write the line.
+    ///
+    /// Why: append-only so the file acts as a running log rather than
+    /// requiring the agent to track and rewrite existing content.
+    ///
+    /// Return: confirmation string echoing the added task, or an error
+    /// if the `task` argument is missing or the file can't be opened/written.
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let task = args.get("task")
             .and_then(|v| v.as_str())