handoff-mcp-server 0.17.1 → 0.18.0

package/Cargo.lock

@@ -136,7 +136,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.17.1"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.17.1"
+version = "0.18.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",

package/scripts/install-local.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Install handoff-mcp locally: binary, skills, and plugin caches.
+# Usage: ./scripts/install-local.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(dirname "$SCRIPT_DIR")"
+CLAUDE_DIR="${HOME}/.claude"
+CACHE_DIR="${CLAUDE_DIR}/plugins/cache/handoff-mcp-marketplace"
+INSTALLED_JSON="${CLAUDE_DIR}/plugins/installed_plugins.json"
+
+cd "$ROOT"
+
+# ---------- 1. Binary ----------
+echo "==> Building release binary..."
+cargo build --release
+
+mkdir -p "${HOME}/.local/bin"
+rm -f "${HOME}/.local/bin/handoff-mcp"
+cp target/release/handoff-mcp "${HOME}/.local/bin/handoff-mcp"
+echo "    Installed: $(${HOME}/.local/bin/handoff-mcp --version)"
+
+# ---------- 2. Bundled skills ----------
+echo "==> Syncing skills..."
+skill_count=0
+for skill in skills/*/; do
+  name=$(basename "$skill")
+  mkdir -p "${CLAUDE_DIR}/skills/${name}"
+  cp "${skill}SKILL.md" "${CLAUDE_DIR}/skills/${name}/SKILL.md"
+  skill_count=$((skill_count + 1))
+done
+echo "    ${skill_count} skills synced"
+
+# ---------- 3. Sync plugin distribution skills ----------
+echo "==> Syncing plugin distribution skills..."
+"${SCRIPT_DIR}/sync-plugin-skills.sh"
+
+# ---------- 4. Plugin caches ----------
+echo "==> Syncing plugin caches..."
+
+sync_plugin() {
+  local src_dir="$1"
+  local plugin_json="${src_dir}/.claude-plugin/plugin.json"
+
+  if [ ! -f "$plugin_json" ]; then
+    echo "    SKIP: ${src_dir} (no .claude-plugin/plugin.json)"
+    return
+  fi
+
+  local name version cache_dest
+  name=$(python3 -c "import json,sys; print(json.load(sys.stdin)['name'])" < "$plugin_json")
+  version=$(python3 -c "import json,sys; print(json.load(sys.stdin)['version'])" < "$plugin_json")
+  cache_dest="${CACHE_DIR}/${name}/${version}"
+
+  rm -rf "$cache_dest"
+  mkdir -p "$cache_dest"
+
+  # Copy everything except .claude-plugin/ first, then copy .claude-plugin/
+  find "$src_dir" -mindepth 1 -maxdepth 1 -not -name '.claude-plugin' -exec cp -a {} "$cache_dest/" \;
+  cp -a "${src_dir}/.claude-plugin" "$cache_dest/.claude-plugin"
+
+  echo "    ${name}@${version} -> ${cache_dest}"
+
+  # Update installed_plugins.json timestamp
+  if [ -f "$INSTALLED_JSON" ] && command -v python3 >/dev/null 2>&1; then
+    local git_sha
+    git_sha=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
+    local now
+    now=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+    python3 -c "
+import json, sys
+key = '${name}@handoff-mcp-marketplace'
+with open('${INSTALLED_JSON}', 'r') as f:
+    data = json.load(f)
+if key in data.get('plugins', {}):
+    for entry in data['plugins'][key]:
+        entry['installPath'] = '${cache_dest}'
+        entry['version'] = '${version}'
+        entry['lastUpdated'] = '${now}'
+        entry['gitCommitSha'] = '${git_sha}'
+    with open('${INSTALLED_JSON}', 'w') as f:
+        json.dump(data, f, indent=4)
+        f.write('\n')
+" 2>/dev/null || true
+  fi
+}
+
+sync_plugin "${ROOT}/plugin"
+sync_plugin "${ROOT}/plugin-hooks"
+sync_plugin "${ROOT}/plugin-task-loop"
+
+# ---------- 5. Verify ----------
+echo ""
+echo "==> Done. Restart Claude Code to pick up changes."
+echo "    Binary:  ${HOME}/.local/bin/handoff-mcp"
+echo "    Skills:  ${CLAUDE_DIR}/skills/"
+echo "    Plugins: ${CACHE_DIR}/"

package/src/mcp/handlers/config.rs

@@ -58,6 +58,7 @@ pub fn handle_update(arguments: &Value) -> Result<String> {
         "settings.timer_idle_timeout_minutes",
         "dashboard.scan_dirs",
         "dashboard.exclude_patterns",
+        "dashboard.max_depth",
         "project.name",
         "project.description",
     ];
@@ -241,6 +242,16 @@ pub fn handle_update(arguments: &Value) -> Result<String> {
                         ));
                     }
                 }
+                "dashboard.max_depth" => {
+                    let Some(n) = value.as_u64() else {
+                        anyhow::bail!("dashboard.max_depth must be a non-negative integer");
+                    };
+                    if n == 0 {
+                        anyhow::bail!("dashboard.max_depth must be >= 1");
+                    }
+                    config.dashboard.max_depth = n as usize;
+                    applied.push(format!("dashboard.max_depth = {n}"));
+                }
                 "project.name" => {
                     if let Some(s) = value.as_str() {
                         config.project.name = s.to_string();

package/src/mcp/handlers/dashboard.rs

@@ -1,9 +1,9 @@
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
 use anyhow::{Context, Result};
 use serde_json::Value;
 
-use crate::storage::config::read_config;
+use crate::storage::config::{read_config, DashboardConfig};
 use crate::storage::expand_tilde;
 use crate::storage::referrals::read_referral_summaries;
 use crate::storage::sessions::{read_active_sessions, read_open_sessions, read_paused_sessions};
@@ -32,23 +32,18 @@ pub fn handle(arguments: &Value) -> Result<String> {
             continue;
         }
 
-        let entries = match std::fs::read_dir(expanded_path) {
-            Ok(e) => e,
-            Err(_) => continue,
-        };
+        let (max_depth, exclude_patterns) = resolve_scan_config(expanded_path, arguments);
 
-        for entry in entries.flatten() {
-            if !entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
-                continue;
-            }
-
-            let project_path = entry.path();
-            let handoff_dir = project_path.join(".handoff");
-
-            if !handoff_dir.join("config.toml").exists() {
-                continue;
-            }
+        let mut discovered = Vec::new();
+        scan_recursive(
+            expanded_path,
+            1,
+            max_depth,
+            &exclude_patterns,
+            &mut discovered,
+        );
 
+        for project_path in discovered {
             if let Ok(info) = collect_project_info(&project_path) {
                 total_active += info["active_tasks"].as_u64().unwrap_or(0) as u32;
                 total_blocked += info["blocked_tasks"].as_u64().unwrap_or(0) as u32;
@@ -66,6 +61,112 @@ pub fn handle(arguments: &Value) -> Result<String> {
     serde_json::to_string_pretty(&result).context("Failed to serialize dashboard")
 }
 
+/// Resolves effective `max_depth` / `exclude_patterns` for a single scan_dir.
+///
+/// Precedence: explicit tool `arguments` override (applies uniformly across
+/// all scan_dirs, since it's an explicit user choice), then this scan_dir's
+/// own `.handoff/config.toml` (if present), then — in the common umbrella-
+/// workspace topology where the scan_dir itself is not a handoff project (e.g.
+/// `~/pro/`) — the first *discovered child* project's config within this same
+/// scan_dir's subtree, then built-in defaults.
+///
+/// Scoped to a single `expanded_path` so config discovered under one scan_dir
+/// never leaks into sibling scan_dirs in a multi-root dashboard call.
+fn resolve_scan_config(expanded_path: &Path, arguments: &Value) -> (usize, Vec<String>) {
+    let mut defaults = DashboardConfig::default();
+
+    let own_config_path = expanded_path.join(".handoff").join("config.toml");
+    if let Ok(config) = read_config(&own_config_path) {
+        defaults = config.dashboard;
+    } else {
+        // scan_dir itself has no config of its own (typical umbrella-workspace
+        // case) — do a discovery pass scoped to this scan_dir's own subtree and
+        // look for a child project whose own dashboard config overrides the
+        // built-in default, so per-project settings still take effect without
+        // requiring an explicit tool argument. Discovery order is filesystem-
+        // dependent, so sort child paths for deterministic selection.
+        //
+        // Probe depth is capped at the caller's explicit max_depth argument
+        // (if given) so a shallow-depth request doesn't still pay for a full
+        // default-depth (5) filesystem walk just to look for fallback config.
+        let probe_depth = arguments
+            .get("max_depth")
+            .and_then(|v| v.as_u64())
+            .map(|n| n as usize)
+            .unwrap_or_else(|| DashboardConfig::default().max_depth)
+            .min(DashboardConfig::default().max_depth);
+        let mut discovered = Vec::new();
+        scan_recursive(expanded_path, 1, probe_depth, &[], &mut discovered);
+        discovered.sort();
+        for child_path in discovered {
+            let child_config_path = child_path.join(".handoff").join("config.toml");
+            if let Ok(config) = read_config(&child_config_path) {
+                if config.dashboard.max_depth != DashboardConfig::default().max_depth
+                    || !config.dashboard.exclude_patterns.is_empty()
+                {
+                    defaults = config.dashboard;
+                    break;
+                }
+            }
+        }
+    }
+
+    let max_depth = arguments
+        .get("max_depth")
+        .and_then(|v| v.as_u64())
+        .map(|n| n as usize)
+        .unwrap_or(defaults.max_depth);
+
+    let exclude_patterns = arguments
+        .get("exclude_patterns")
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| v.as_str().map(String::from))
+                .collect()
+        })
+        .unwrap_or(defaults.exclude_patterns);
+
+    (max_depth, exclude_patterns)
+}
+
+/// Recursively scans `dir` up to `max_depth` levels for `.handoff/config.toml`
+/// markers, skipping directories whose name exactly matches an entry in
+/// `exclude_patterns`. Never descends into a directory literally named
+/// `.handoff` — a project's own bookkeeping tree (tasks/sessions/memory/etc.)
+/// can never contain a nested project marker, so walking it would only waste
+/// I/O proportional to the project's task/session history.
+fn scan_recursive(
+    dir: &Path,
+    depth: usize,
+    max_depth: usize,
+    exclude_patterns: &[String],
+    results: &mut Vec<PathBuf>,
+) {
+    if depth > max_depth {
+        return;
+    }
+    let entries = match std::fs::read_dir(dir) {
+        Ok(e) => e,
+        Err(_) => return,
+    };
+    for entry in entries.flatten() {
+        if !entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
+            continue;
+        }
+        let name = entry.file_name();
+        let name_str = name.to_string_lossy();
+        if name_str == ".handoff" || exclude_patterns.iter().any(|p| p == name_str.as_ref()) {
+            continue;
+        }
+        let path = entry.path();
+        if path.join(".handoff").join("config.toml").exists() {
+            results.push(path.clone());
+        }
+        scan_recursive(&path, depth + 1, max_depth, exclude_patterns, results);
+    }
+}
+
 fn collect_project_info(project_path: &Path) -> Result<Value> {
     let handoff_dir = project_path.join(".handoff");
     let config = read_config(&handoff_dir.join("config.toml"))?;

package/src/mcp/handlers/list_tasks.rs

@@ -1,10 +1,19 @@
+use std::path::{Path, PathBuf};
+
 use anyhow::{Context, Result};
-use serde_json::Value;
+use serde_json::{json, Value};
 
 use super::resolve_project_dir;
 use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
-use crate::storage::tasks::{build_task_index, TaskIndex};
+use crate::storage::tasks::{build_task_index, TaskIndex, TaskSummary};
+
+/// Maximum depth (relative to the base project dir) scanned for nested
+/// `.handoff/` child projects.
+const MAX_CHILD_SCAN_DEPTH: usize = 5;
+
+/// Directory names skipped while scanning for child projects.
+const DEFAULT_SCAN_EXCLUDES: &[&str] = &["node_modules", ".git", "target", "dist", ".next"];
 
 pub fn handle(arguments: &Value) -> Result<String> {
     let project_dir = resolve_project_dir(arguments)?;
@@ -43,14 +52,183 @@ pub fn handle(arguments: &Value) -> Result<String> {
         tree
     };
 
+    let include_children = arguments
+        .get("include_children")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+
+    if !include_children {
+        let result = serde_json::json!({
+            "task_tree": filtered_tree,
+            "task_summary": summary,
+        });
+        return serde_json::to_string_pretty(&result).context("Failed to serialize task list");
+    }
+
+    // Determine own project name for annotation (defaults to config, fallback to "root").
+    let own_project_name = if config_path.exists() {
+        read_config(&config_path)
+            .map(|c| c.project.name)
+            .unwrap_or_else(|_| "root".to_string())
+    } else {
+        "root".to_string()
+    };
+    let own_project_dir = project_dir.to_string_lossy().to_string();
+
+    let mut aggregated: Vec<Value> =
+        annotate_tasks_json(filtered_tree, &own_project_name, &own_project_dir);
+    let mut total_summary = summary;
+
+    for (child_name, child_dir) in discover_child_projects(&project_dir, MAX_CHILD_SCAN_DEPTH) {
+        let child_handoff = child_dir.join(".handoff");
+        let child_tasks_dir = child_handoff.join("tasks");
+        let child_config_path = child_handoff.join("config.toml");
+        let child_done_task_limit = read_config(&child_config_path)
+            .map(|c| c.settings.done_task_limit)
+            .unwrap_or(10);
+
+        let (child_tree, child_summary) =
+            match build_task_index(&child_tasks_dir, child_done_task_limit) {
+                Ok(v) => v,
+                Err(_) => continue,
+            };
+
+        let child_filtered = if filters.any_active() {
+            filter_tree(&child_tree, &filters)
+        } else {
+            child_tree
+        };
+
+        let child_dir_str = child_dir.to_string_lossy().to_string();
+        aggregated.extend(annotate_tasks_json(
+            child_filtered,
+            &child_name,
+            &child_dir_str,
+        ));
+        merge_summary(&mut total_summary, &child_summary);
+    }
+
     let result = serde_json::json!({
-        "task_tree": filtered_tree,
-        "task_summary": summary,
+        "task_tree": aggregated,
+        "task_summary": total_summary,
     });
 
     serde_json::to_string_pretty(&result).context("Failed to serialize task list")
 }
 
+fn merge_summary(base: &mut TaskSummary, other: &TaskSummary) {
+    base.total += other.total;
+    for (status, count) in &other.by_status {
+        *base.by_status.entry(status.clone()).or_insert(0) += count;
+    }
+    base.overdue_count += other.overdue_count;
+    if let Some(other_est) = other.total_estimate_hours {
+        base.total_estimate_hours = Some(base.total_estimate_hours.unwrap_or(0.0) + other_est);
+    }
+    if let Some(other_act) = other.total_actual_hours {
+        base.total_actual_hours = Some(base.total_actual_hours.unwrap_or(0.0) + other_act);
+    }
+    if base.total > 0 {
+        let done = *base.by_status.get("done").unwrap_or(&0) as f64;
+        let skipped = *base.by_status.get("skipped").unwrap_or(&0) as f64;
+        base.completion_rate = Some((done + skipped) / base.total as f64);
+    }
+}
+
+/// Annotate a task tree with `project_name`/`project_dir` and a composite
+/// `task_ref` disambiguator (`{project_name}-{project_dir_hash}:{id}`) for
+/// cross-project display purposes.
+///
+/// The original `id` field is deliberately left **unmodified**: it is the
+/// value accepted by `handoff_get_task`/`handoff_update_task`/etc. (scoped by
+/// the sibling `project_dir` field), and it is also what `dependencies`
+/// entries reference. Rewriting `id` would make it unusable with every other
+/// tool and would desync it from `dependencies`, which still contain raw ids.
+///
+/// `project_name` alone is free-form user text with no cross-directory
+/// uniqueness guarantee, so two child projects can share the same name. The
+/// `task_ref` additionally embeds a short hash of `project_dir` (which is
+/// unique per filesystem location) to guarantee it never collides even when
+/// `project_name` is duplicated.
+fn annotate_tasks_json(tasks: Vec<TaskIndex>, project_name: &str, project_dir: &str) -> Vec<Value> {
+    let dir_hash = short_hash(project_dir);
+    tasks
+        .into_iter()
+        .map(|t| {
+            let mut v = serde_json::to_value(&t).unwrap_or_default();
+            if let Some(obj) = v.as_object_mut() {
+                obj.insert("project_name".to_string(), json!(project_name));
+                obj.insert("project_dir".to_string(), json!(project_dir));
+                if let Some(id) = obj.get("id").and_then(|v| v.as_str()).map(String::from) {
+                    obj.insert(
+                        "task_ref".to_string(),
+                        json!(format!("{project_name}-{dir_hash}:{id}")),
+                    );
+                }
+                if let Some(children) = obj.remove("children") {
+                    if let Ok(child_tasks) = serde_json::from_value::<Vec<TaskIndex>>(children) {
+                        obj.insert(
+                            "children".to_string(),
+                            json!(annotate_tasks_json(child_tasks, project_name, project_dir)),
+                        );
+                    }
+                }
+            }
+            v
+        })
+        .collect()
+}
+
+/// Deterministic short hash (FNV-1a, hex-encoded) used to disambiguate
+/// composite task IDs across child projects that share a `project_name`.
+/// Not a dependency addition — plain FNV-1a is sufficient since this only
+/// needs to be stable and collision-resistant for distinct directory paths,
+/// not cryptographically secure.
+fn short_hash(input: &str) -> String {
+    const FNV_OFFSET_BASIS: u64 = 0xcbf29ce484222325;
+    const FNV_PRIME: u64 = 0x100000001b3;
+    let mut hash = FNV_OFFSET_BASIS;
+    for byte in input.as_bytes() {
+        hash ^= u64::from(*byte);
+        hash = hash.wrapping_mul(FNV_PRIME);
+    }
+    format!("{hash:08x}")
+}
+
+fn discover_child_projects(base: &Path, max_depth: usize) -> Vec<(String, PathBuf)> {
+    let mut results = Vec::new();
+    scan_children(base, 1, max_depth, &mut results);
+    results
+}
+
+fn scan_children(dir: &Path, depth: usize, max_depth: usize, results: &mut Vec<(String, PathBuf)>) {
+    if depth > max_depth {
+        return;
+    }
+    let entries = match std::fs::read_dir(dir) {
+        Ok(e) => e,
+        Err(_) => return,
+    };
+    for entry in entries.flatten() {
+        if !entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
+            continue;
+        }
+        let name = entry.file_name();
+        let name_str = name.to_string_lossy();
+        if name_str.starts_with('.') || DEFAULT_SCAN_EXCLUDES.contains(&name_str.as_ref()) {
+            continue;
+        }
+        let path = entry.path();
+        let config_path = path.join(".handoff").join("config.toml");
+        if config_path.exists() {
+            if let Ok(config) = read_config(&config_path) {
+                results.push((config.project.name.clone(), path.clone()));
+            }
+        }
+        scan_children(&path, depth + 1, max_depth, results);
+    }
+}
+
 struct Filters<'a> {
     status: Option<&'a str>,
     assignee: Option<&'a str>,

package/src/mcp/handlers/load_context.rs

@@ -1,3 +1,5 @@
+use std::path::Path;
+
 use anyhow::{Context, Result};
 use serde_json::Value;
 
@@ -12,6 +14,13 @@ use crate::storage::sessions::{
 use crate::storage::tasks::{build_task_index, TaskIndex};
 use crate::storage::{ensure_handoff_exists, handoff_dir};
 
+/// Maximum depth (relative to the base project dir) scanned for nested
+/// `.handoff/` child projects.
+const MAX_CHILD_SCAN_DEPTH: usize = 5;
+
+/// Directory names skipped while scanning for child projects.
+const DEFAULT_SCAN_EXCLUDES: &[&str] = &["node_modules", ".git", "target", "dist", ".next"];
+
 pub fn handle(arguments: &Value) -> Result<String> {
     let project_dir = resolve_project_dir(arguments)?;
 
@@ -261,6 +270,10 @@ pub fn handle(arguments: &Value) -> Result<String> {
         });
     }
 
+    // Always include child_projects (empty array if none).
+    let child_projects = discover_child_project_info(&project_dir);
+    result["child_projects"] = serde_json::json!(child_projects);
+
     serde_json::to_string_pretty(&result).context("Failed to serialize context")
 }
 
@@ -301,3 +314,48 @@ fn collect_active_ids_recursive(tasks: &[TaskIndex], ids: &mut Vec<String>) {
         collect_active_ids_recursive(&task.children, ids);
     }
 }
+
+fn discover_child_project_info(base: &Path) -> Vec<Value> {
+    let mut results = Vec::new();
+    scan_for_children(base, 1, MAX_CHILD_SCAN_DEPTH, &mut results);
+    results
+}
+
+fn scan_for_children(dir: &Path, depth: usize, max_depth: usize, results: &mut Vec<Value>) {
+    if depth > max_depth {
+        return;
+    }
+    let entries = match std::fs::read_dir(dir) {
+        Ok(e) => e,
+        Err(_) => return,
+    };
+    for entry in entries.flatten() {
+        if !entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
+            continue;
+        }
+        let name = entry.file_name();
+        let name_str = name.to_string_lossy();
+        if name_str.starts_with('.') || DEFAULT_SCAN_EXCLUDES.contains(&name_str.as_ref()) {
+            continue;
+        }
+        let path = entry.path();
+        let handoff_dir = path.join(".handoff");
+        let config_path = handoff_dir.join("config.toml");
+        if config_path.exists() {
+            if let Ok(config) = read_config(&config_path) {
+                let tasks_dir = handoff_dir.join("tasks");
+                let (_, summary) = match build_task_index(&tasks_dir, 10) {
+                    Ok(result) => result,
+                    Err(_) => continue,
+                };
+                results.push(serde_json::json!({
+                    "name": config.project.name,
+                    "dir": path.to_string_lossy(),
+                    "task_count": summary.total,
+                    "status_summary": summary.by_status,
+                }));
+            }
+        }
+        scan_for_children(&path, depth + 1, max_depth, results);
+    }
+}

package/src/mcp/handlers/mod.rs

@@ -35,11 +35,16 @@ use serde_json::Value;
 use crate::mcp::types::JsonRpcResponse;
 
 pub fn resolve_project_dir(arguments: &Value) -> Result<PathBuf> {
-    let raw = match arguments.get("project_dir").and_then(|v| v.as_str()) {
+    let raw = match arguments
+        .get("project_dir")
+        .and_then(|v| v.as_str())
+        .filter(|s| !s.is_empty() && !s.starts_with("${"))
+    {
         Some(dir) => PathBuf::from(dir),
         None => std::env::current_dir().context("Failed to get current directory")?,
     };
-    std::fs::canonicalize(&raw).with_context(|| format!("Invalid project path: {}", raw.display()))
+    std::fs::canonicalize(&raw)
+        .with_context(|| format!("Invalid project path: {raw}", raw = raw.display()))
 }
 
 pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {

package/src/mcp/tools.rs

@@ -221,6 +221,10 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "label_filter": {
                         "type": "string",
                         "description": "Filter by label (task must contain this label)."
+                    },
+                    "include_children": {
+                        "type": "boolean",
+                        "description": "If true, recursively scan project_dir for child .handoff/ projects and include their tasks. Each task gets project_name, project_dir, and task_ref fields (task_ref is a composite '{project_name}-{hash}:{id}' identifier unique across projects). The original 'id' field is left unchanged so it stays usable with handoff_get_task/handoff_update_task/dependencies when paired with the task's own project_dir. Default: false."
                     }
                 }
             }),
@@ -395,6 +399,15 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "items": { "type": "string" },
                         "description": "Directories to scan. Defaults to config's dashboard.scan_dirs."
                     },
+                    "max_depth": {
+                        "type": "integer",
+                        "description": "Maximum directory depth for recursive scanning. Defaults to config's dashboard.max_depth (5)."
+                    },
+                    "exclude_patterns": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "description": "Directory names to skip during recursive scanning (exact match). Defaults to config's dashboard.exclude_patterns."
+                    },
                     "include_completed": {
                         "type": "boolean",
                         "description": "Include completed tasks in summary"

package/src/storage/config.rs

@@ -103,6 +103,9 @@ pub struct DashboardConfig {
     pub scan_dirs: Vec<String>,
     #[serde(default)]
     pub exclude_patterns: Vec<String>,
+    /// Maximum directory depth for recursive scanning. Default 5 (mirrors VSCode side).
+    #[serde(default = "default_max_depth")]
+    pub max_depth: usize,
 }
 
 /// Project-wide working calendar. Mirrors VSCode `CalendarConfig`.
@@ -280,6 +283,10 @@ fn default_scan_dirs() -> Vec<String> {
     vec!["~/pro/".to_string()]
 }
 
+fn default_max_depth() -> usize {
+    5
+}
+
 impl Default for SettingsConfig {
     fn default() -> Self {
         Self {
@@ -309,6 +316,7 @@ impl Default for DashboardConfig {
         Self {
             scan_dirs: default_scan_dirs(),
             exclude_patterns: Vec::new(),
+            max_depth: default_max_depth(),
         }
     }
 }