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/mod.rs

@@ -1,3 +1,5 @@
+//! Tool trait, execution context, and the registry of all 28 built-in tools.
+
 use std::path::PathBuf;
 use serde_json::Value;
 use anyhow::Result;
@@ -16,6 +18,7 @@ pub mod shell_filter;
 pub mod utility;
 pub mod workflow;
 
+/// Common interface every agent-invocable tool implements: name, JSON schema, and execution.
 pub trait Tool: Send + Sync {
     fn name(&self) -> &'static str;
     fn description(&self) -> &'static str;
@@ -23,6 +26,7 @@ pub trait Tool: Send + Sync {
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String>;
 }
 
+/// A project-defined rule that flags a matching file path or content pattern for review.
 #[derive(Debug, Clone)]
 pub struct GraduatedCheck {
     pub name: String,
@@ -30,6 +34,8 @@ pub struct GraduatedCheck {
     pub rule: String,
 }
 
+/// Shared execution context passed to every `Tool::run` call: workspace roots, session
+/// paths, and cached directory state.
 #[derive(Clone)]
 pub struct ToolCtx {
     pub workspaces: Vec<PathBuf>,
@@ -42,6 +48,12 @@ pub struct ToolCtx {
     pub graduated_checks: Vec<GraduatedCheck>,
 }
 
+/// Find which graduated checks apply to a given file path/content pair.
+///
+/// Flow: for each check, match its `pattern` against `path` or its `rule` against
+///       `content` (substring match) → collect matching check names.
+///
+/// Return: names of all matching checks; empty if none match.
 pub fn check_graduated_checks(path: &str, content: &str, checks: &[GraduatedCheck]) -> Vec<String> {
     let mut matches = Vec::new();
     for check in checks {
@@ -53,11 +65,13 @@ pub fn check_graduated_checks(path: &str, content: &str, checks: &[GraduatedChec
 }
 
 impl ToolCtx {
+    /// Start building a `ToolCtx` with `ToolCtxBuilder`'s defaults.
     pub fn builder() -> ToolCtxBuilder {
         ToolCtxBuilder::default()
     }
 }
 
+/// Builder for `ToolCtx`; fields default to empty paths and a fresh `DirCache`.
 pub struct ToolCtxBuilder {
     pub workspaces: Vec<PathBuf>,
     pub session_dir: PathBuf,
@@ -85,8 +99,11 @@ impl Default for ToolCtxBuilder {
 }
 
 impl ToolCtxBuilder {
+    /// Set the session directory.
     pub fn session_dir(mut self, v: PathBuf) -> Self { self.session_dir = v; self }
+    /// Set the origin (main process vs. daemon-attached).
     pub fn origin(mut self, v: crate::app::state::types::Origin) -> Self { self.origin = v; self }
+    /// Consume the builder and produce the final `ToolCtx`.
     pub fn build(self) -> ToolCtx {
         ToolCtx {
             workspaces: self.workspaces,
@@ -101,6 +118,10 @@ impl ToolCtxBuilder {
     }
 }
 
+/// Construct one instance of every built-in tool, in the fixed order exposed to the LLM.
+///
+/// Return: boxed trait objects for all 28 tools (fs, search, bash, git, memory, plan,
+/// workflow, utility).
 pub fn all_tools() -> Vec<Box<dyn Tool>> {
     vec![
         Box::new(super::tool::fs::read::Read),
@@ -131,10 +152,16 @@ pub fn all_tools() -> Vec<Box<dyn Tool>> {
     ]
 }
 
+/// Whether a tool by name can mutate the filesystem or run arbitrary shell commands.
+///
+/// Why: used by the harness to decide which tool calls need user confirmation/guard checks.
 pub fn tool_is_risky(name: &str) -> bool {
     matches!(name, "write" | "delete" | "edit" | "bash" | "git_operator")
 }
 
+/// Convert a list of tools into the provider-facing `ToolDef` request schema.
+///
+/// Return: one `ToolDef` per tool, in the same order as `tools`.
 pub fn tool_defs(tools: &[Box<dyn Tool>]) -> Vec<crate::dto::provider::request::ToolDef> {
     tools
         .iter()
@@ -149,6 +176,18 @@ pub fn tool_defs(tools: &[Box<dyn Tool>]) -> Vec<crate::dto::provider::request::
         .collect()
 }
 
+/// Resolve a tool-supplied relative path to an absolute path within a workspace root,
+/// rejecting escapes.
+///
+/// Flow: parse optional `[N]` workspace-index prefix (defaults to workspace 0) → join
+///       remainder onto that workspace root → canonicalize → verify the canonical path
+///       still starts with one of `workspaces`.
+///
+/// Why: canonicalizing and re-checking containment (rather than trusting the join)
+/// prevents `../` traversal from escaping the sandboxed workspace roots.
+///
+/// Return: the canonical absolute path, or an error if the workspace index is invalid
+/// or the resolved path falls outside all workspace roots.
 pub fn resolve_path(workspaces: &[PathBuf], rel: &str) -> Result<PathBuf> {
     let _parts: Vec<&str> = rel.splitn(2, '/').collect();
     let (ws_idx, path) = if rel.starts_with('[') {