Enhance logging and documentation across utility tools and TUI overlays

- Added tracing instrumentation and improved logging messages in the Pong, Todofinish, and Todowrite tools for better debugging and monitoring.
- Enhanced documentation comments for clarity on tool functionalities and workflows.
- Implemented tracing in WorkflowRun, NoteFinding, ReadFindings, and HiveMind tools to track execution phases and findings.
- Updated TUI overlays (e.g., Bash, Clear Confirm, Editor, Effort Level, Help, Key Input, Learning, Loading, MCP, Model Selector, Plan, Quit Confirm, Rewind, Settings, Todo, Usage) with debug logging to capture rendering details.
- Improved the status bar and workflow panel rendering with additional debug information.
- Added tracing to various utility functions to facilitate better performance monitoring and error tracking.

apps/infrastructure/src/subagent/engine.rs

@@ -5,7 +5,7 @@
 //! tool calls) or the iteration limit is reached.
 
 use anyhow::Result;
-use tracing::{debug, info};
+use tracing::{debug, info, instrument};
 
 use crate::llm::provider::LlmClient;
 use crate::subagent::context::SubagentContext;
@@ -29,6 +29,7 @@ const MAX_ITERATIONS: u32 = 25;
 ///      tool-role message.
 ///      d. If the response also contained text, append an assistant message.
 ///   4. If the loop exits naturally, return the iteration-limit message.
+#[instrument(skip(ctx, tool_ctx))]
 pub async fn run_agent(
     ctx: SubagentContext,
     directive: &str,

apps/infrastructure/src/subagent/gating.rs

@@ -1,7 +1,16 @@
 //! Subagent gating — decide whether to run review/test/arch agents based
 //! on the current context.
 
+use tracing::instrument;
+
 /// Determine whether an auto-review should be triggered after an edit.
+///
+/// Gating logic:
+/// - Returns `false` if there are no edits (`edit_count == 0`).
+/// - Returns `false` if `consecutive_empty_reviews >= max_skip` (too many
+///   consecutive reviews produced no findings, so skip further reviews).
+/// - Otherwise returns `true`.
+#[instrument]
 pub fn should_review(edit_count: u32, consecutive_empty_reviews: u32, max_skip: u32) -> bool {
     if edit_count == 0 {
         return false;

apps/infrastructure/src/subagent/provider.rs

@@ -6,6 +6,7 @@
 //!   inside the subagent engine loop.
 
 use anyhow::Result;
+use tracing::instrument;
 
 use crate::llm::provider::LlmClient;
 use crate::tools::{tool_defs, Tool};
@@ -25,6 +26,7 @@ pub struct SubagentProvider {
 
 impl SubagentProvider {
     /// Wrap an existing `LlmClient` for higher-level use.
+    #[instrument(skip(client))]
     pub fn new(client: LlmClient) -> Self {
         Self { client }
     }
@@ -32,6 +34,7 @@ impl SubagentProvider {
     /// Send messages to the LLM without any tool definitions.
     ///
     /// Use this for a plain text-in/text-out conversation.
+    #[tracing::instrument(skip(self, messages))]
     pub fn chat(
         &self,
         messages: &[ChatMessage],
@@ -44,6 +47,7 @@ impl SubagentProvider {
     ///
     /// Automatically converts the `&[Box<dyn Tool>]` slice to
     /// `Vec<ToolDef>` before passing to the underlying client.
+    #[tracing::instrument(skip(self, messages, tools))]
     pub fn chat_with_tools(
         &self,
         messages: &[ChatMessage],
@@ -60,6 +64,7 @@ impl SubagentProvider {
 /// Flow: reads `settings.provider` and `settings.model` → if model is empty,
 /// falls back to the provider config's `default_model` → if that is also
 /// empty, uses `"deepseek-v4-flash-free"` as the ultimate default.
+#[instrument]
 pub fn resolve_subagent_provider(
     settings: &zesdex_domain::cms::Settings,
     app_config: &zesdex_domain::cms::AppConfig,

apps/infrastructure/src/subagent/spawn.rs

@@ -7,7 +7,7 @@
 use std::thread;
 
 use anyhow::Result;
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::subagent::context::SubagentContext;
 use crate::subagent::division::AccessTier;
@@ -23,6 +23,7 @@ use crate::tools::ToolCtx;
 /// `runtime.block_on(run_agent(...))` → return.
 ///
 /// Returns a `JoinHandle` the caller can `join()` to await the result.
+#[instrument(skip(ctx, tool_ctx))]
 pub fn spawn_subagent(
     ctx: SubagentContext,
     directive: String,

apps/infrastructure/src/subagent/tools.rs

@@ -1,9 +1,15 @@
 //! Subagent tool helpers — wrap tool execution for subagent use.
 
-use crate::tools::{Tool, ToolCtx};
 use anyhow::Result;
+use tracing::instrument;
+
+use crate::tools::{Tool, ToolCtx};
 
 /// Execute a single tool call within a subagent context.
+///
+/// Delegates directly to the tool's `run` method with the given context and
+/// JSON arguments.
+#[instrument(skip(tool, ctx, args))]
 pub fn execute_tool_call(
     tool: &dyn Tool,
     ctx: &ToolCtx,

apps/infrastructure/src/subagent/workspace.rs

@@ -2,7 +2,13 @@
 
 use std::path::{Path, PathBuf};
 
+use tracing::instrument;
+
 /// Create an isolated workspace directory for a subagent.
+///
+/// Creates `{base_dir}/subagent-workspaces/{agent_id}` and all parent
+/// directories if they do not already exist.
+#[instrument]
 pub fn create_subagent_workspace(base_dir: &Path, agent_id: &str) -> anyhow::Result<PathBuf> {
     let ws = base_dir.join("subagent-workspaces").join(agent_id);
     std::fs::create_dir_all(&ws)?;