handoff-mcp-server 0.18.7 → 0.19.1

package/Cargo.lock

@@ -136,7 +136,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.18.7"
+version = "0.19.1"
 dependencies = [
  "anyhow",
  "chrono",
@@ -208,9 +208,9 @@ dependencies = [
 
 [[package]]
 name = "lexsim"
-version = "0.1.0"
+version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "579b9d7ab407540bead4688eaf1675410a198d77c237a30cda55597df98926e1"
+checksum = "14b08f26a4b07325e83c0211adb36d0223fae644534dacd4eae72153c1ccd873"
 dependencies = [
  "unicode-normalization",
  "unicode-segmentation",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.18.7"
+version = "0.19.1"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"
@@ -20,7 +20,7 @@ toml_edit = "0.22"
 chrono = { version = "0.4", features = ["serde"] }
 anyhow = "1"
 thiserror = "2"
-lexsim = "0.1.0"
+lexsim = ">=0.1.0, <1.0.0"
 
 [dev-dependencies]
 tempfile = "3.27.0"

package/README.md

@@ -35,28 +35,38 @@ At session start, the agent calls `handoff_load_context` to pick up where things
 
 ### Claude Code Plugin (recommended)
 
-The easiest way to install handoff-mcp is as a Claude Code plugin:
+The easiest way to install handoff-mcp is as a Claude Code plugin.
 
 ```bash
 # 1. Install the binary (required — the plugin calls it)
 npm install -g handoff-mcp-server
 # or: cargo install handoff-mcp
 
-# 2. Add the marketplace
+# 2. Add the marketplace (GitHub repo)
 /plugin marketplace add alphaelements/handoff-mcp
 
 # 3. Install the plugin (MCP server + skills)
 /plugin install handoff-mcp@handoff-mcp-marketplace
+
+# 4. Apply the change
+/reload-plugins
 ```
 
 This registers the MCP server and all skills automatically — no manual
-`.mcp.json` or skill file setup needed.
+`.mcp.json` or skill file setup needed. The `handoff-mcp` plugin is enabled
+on install, so no separate `/plugin enable` is needed. Run `/reload-plugins`
+to pick up the change mid-session (a Claude Code restart also applies it).
+
+> **Naming**: `handoff-mcp` is the *plugin* name; `handoff-mcp-marketplace`
+> is the *marketplace* name (the `name` field in `.claude-plugin/marketplace.json`).
+> Install commands always use `<plugin>@<marketplace>`.
 
 **Optional: task loop (automated TDD + research workflows)**
 
 ```bash
 /plugin install handoff-task-loop@handoff-mcp-marketplace
-/plugin enable handoff-task-loop
+/plugin enable handoff-task-loop@handoff-mcp-marketplace
+/reload-plugins
 ```
 
 Adds `/session-loop` (parallel TDD implementation, adversarial testing, Opus
@@ -67,12 +77,52 @@ drafting). See [plugin-task-loop/README.md](plugin-task-loop/README.md).
 
 ```bash
 /plugin install handoff-mcp-hooks@handoff-mcp-marketplace
-/plugin enable handoff-mcp-hooks
+/plugin enable handoff-mcp-hooks@handoff-mcp-marketplace
+/reload-plugins
 ```
 
 This adds hooks that inject relevant project memories on every prompt and file
-edit. Disable anytime with `/plugin disable handoff-mcp-hooks` — the MCP server
-and skills remain active.
+edit. Disable anytime with `/plugin disable handoff-mcp-hooks@handoff-mcp-marketplace` —
+the MCP server and skills remain active.
+
+> The `handoff-task-loop` and `handoff-mcp-hooks` plugins ship with
+> `defaultEnabled: false`, so they need an explicit `/plugin enable` step after
+> install. The main `handoff-mcp` plugin is `defaultEnabled: true` and skips it.
+
+**Installing the local development version instead**
+
+If you are hacking on handoff-mcp and want Claude Code to load your local
+checkout rather than the published GitHub version, register the repository root
+(the directory containing `.claude-plugin/marketplace.json`) as a local
+marketplace:
+
+```bash
+# 1. Build the binary and sync skills + plugin caches
+./scripts/install-local.sh
+
+# 2. Register the repo root as a local marketplace (first time only).
+#    Use the local path here — not the alphaelements/handoff-mcp shorthand.
+/plugin marketplace add /absolute/path/to/handoff-mcp
+
+# 3. Install and apply
+/plugin install handoff-mcp@handoff-mcp-marketplace
+/reload-plugins
+```
+
+After the first setup, re-run `./scripts/install-local.sh` whenever you change
+the code, then restart Claude Code (or `/reload-plugins`) to load the rebuilt
+version. Note that `install-local.sh` **only rebuilds the binary and refreshes
+the plugin cache** — it does not register the marketplace or enable the plugin,
+so steps 2 and 3 are a one-time bootstrap.
+
+**Troubleshooting**
+
+- **Plugin or skills don't show up** — run `/reload-plugins`, or restart Claude
+  Code. As a last resort, `rm -rf ~/.claude/plugins/cache` and reinstall.
+- **`plugin not found`** — refresh the catalog with
+  `/plugin marketplace update handoff-mcp-marketplace`, then reinstall.
+- **MCP server won't start** — open `/plugin` → **Errors** tab, and confirm the
+  binary is on your `PATH` (`which handoff-mcp`).
 
 ### cargo
 
@@ -137,8 +187,8 @@ handoff-mcp setup
 ```
 
 This installs Claude Code hooks into `~/.claude/settings.json` that
-automatically call `handoff_memory_query` on every prompt and file edit, and run
-`handoff_memory_cleanup` at session start. Restart Claude Code after running setup.
+automatically call `handoff_memory_query` on every prompt and file edit.
+Restart Claude Code after running setup.
 
 You can check the current status or remove the hooks:
 
@@ -258,7 +308,7 @@ rename) so a concurrent reader never sees a partially-written file.
 | `handoff_memory_save` | Save a durable project memory (lesson/rule/convention/gotcha); detects exact and near-duplicate memories and hands near-duplicates back for AI-driven merge |
 | `handoff_memory_query` | Return the memories most relevant to the current prompt/file (BM25 + scope-path boost); with a `session_id`, suppresses repeats already injected this session |
 | `handoff_memory_delete` | Delete a memory by id (full id or unique prefix) |
-| `handoff_memory_cleanup` | Housekeeping (for SessionStart): silently merge exact duplicates, return near-duplicate/stale recommendations, gc old injection sidecars |
+| `handoff_memory_cleanup` | Manual/CLI housekeeping: silently merge exact duplicates, return near-duplicate/stale recommendations, gc old injection sidecars |
 
 For usage best practices (granularity, scope_paths, conflict handling, cleanup), see `skills/handoff-memory/SKILL.md`.
 See [Project Memory](#project-memory-1) below for what it is and how to wire automatic injection.
@@ -432,7 +482,9 @@ the same memory is **not injected twice in one session** — and an *edited* mem
 |-------|-------|--------|
 | `UserPromptSubmit` | `handoff_memory_query` (prompt text) | Inject memories relevant to the prompt |
 | `PreToolUse` (`Edit\|Write\|MultiEdit`) | `handoff_memory_query` (file path) | Inject memories scoped to the file being edited |
-| `SessionStart` | `handoff_memory_cleanup` | Merge exact duplicates, gc old sidecars |
+
+`handoff_memory_cleanup` (merge exact duplicates, gc old sidecars) is not wired
+to a hook — call it manually or from a CLI/cron job when you want housekeeping.
 
 > **Wire hooks in your *user/global* settings, not in the repo.** Hooks are a
 > personal workflow choice; the handoff-mcp repo does not ship a `.claude/`
@@ -462,12 +514,6 @@ MCP tool from a hook directly, with no wrapper script. In
                    "text": "${tool_input.file_path}",
                    "file_paths": ["${tool_input.file_path}"] }
       } ] }
-    ],
-    "SessionStart": [
-      { "hooks": [ {
-        "type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_cleanup",
-        "input": { "project_dir": "${cwd}" }
-      } ] }
     ]
   }
 }
@@ -493,10 +539,6 @@ both paths parse it identically. Point all three hooks at it:
     "PreToolUse": [
       { "matcher": "Edit|Write|MultiEdit", "hooks": [ { "type": "command",
         "command": "/path/to/handoff-mcp/scripts/handoff-memory-hook.py" } ] }
-    ],
-    "SessionStart": [
-      { "hooks": [ { "type": "command",
-        "command": "/path/to/handoff-mcp/scripts/handoff-memory-hook.py" } ] }
     ]
   }
 }
@@ -506,6 +548,32 @@ The script resolves the `handoff-mcp` binary from `PATH` (override with
 `HANDOFF_MCP_BIN`) and **fails safe**: on any error it prints nothing and exits
 0, so a memory miss is silent and never blocks your prompt.
 
+### Upgrading from a version with a `SessionStart` cleanup hook
+
+Versions before this fix had `handoff-mcp setup` (and the
+`handoff-mcp-hooks` plugin) install a **synchronous `SessionStart` hook**
+that ran `handoff_memory_cleanup` on every session start. Under many
+parallel sub-agents (e.g. `/research-loop`), that hook could pile up heavy
+cleanup calls on the single-threaded server and hang your editor.
+
+The `SessionStart` cleanup hook has been removed entirely — `memory_cleanup`
+is still available, but only via manual/CLI invocation, never auto-fired.
+If you already ran `handoff-mcp setup` before this change, migrate with
+**one** of the following:
+
+- **Re-run setup** (recommended): `handoff-mcp setup`. It now detects and
+  automatically strips the legacy `SessionStart` cleanup hook while leaving
+  your other handoff hooks untouched. Use `handoff-mcp setup --check` first
+  if you want to confirm whether the legacy hook is present before touching
+  anything.
+- **Manual edit**: open `~/.claude/settings.json` and delete the
+  `hooks.SessionStart` entry whose `tool` is `handoff_memory_cleanup` (remove
+  the whole `SessionStart` key if that was its only entry).
+- **Plugin users**: `/plugin update` to pick up the new `hooks.json`, then
+  restart Claude Code.
+
+Restart Claude Code after any of the above for the change to take effect.
+
 ### Memory settings
 
 All under `[settings]` in `.handoff/config.toml`, all with safe defaults

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.18.7",
+  "version": "0.19.1",
   "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

@@ -1,6 +1,18 @@
 #!/usr/bin/env bash
 # Install handoff-mcp locally: binary, skills, and plugin caches.
 # Usage: ./scripts/install-local.sh
+#
+# SCOPE: this script rebuilds the binary and refreshes the plugin CACHE only.
+# It does NOT register the marketplace (known_marketplaces.json) or enable the
+# plugin (enabledPlugins in settings.json), and it only updates
+# installed_plugins.json entries that already exist. So on a fresh machine it
+# does not activate the plugin by itself — bootstrap once with:
+#     /plugin marketplace add /absolute/path/to/handoff-mcp
+#     /plugin install handoff-mcp@handoff-mcp-marketplace
+#     /reload-plugins
+# Thereafter, re-run this script to pick up code changes, then restart Claude
+# Code (or /reload-plugins). See README "Installing the local development
+# version instead".
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

package/scripts/sync-plugin-version.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Sync plugin/marketplace manifest versions to package.json's version.
+#
+# package.json is the source of truth (kept in sync with Cargo.toml manually
+# per CLAUDE.md "Version sync" rule). This script propagates that version to:
+#   - plugin/.claude-plugin/plugin.json
+#   - plugin-hooks/.claude-plugin/plugin.json
+#   - plugin-task-loop/.claude-plugin/plugin.json
+#   - .claude-plugin/marketplace.json (all three "version" entries)
+#
+# Uses regex line replacement (not json.dump) so untouched formatting in
+# these hand-maintained manifests is preserved byte-for-byte.
+#
+# Usage:
+#   ./scripts/sync-plugin-version.sh          # fix mismatches in place
+#   ./scripts/sync-plugin-version.sh --check  # exit 1 if anything is out of sync, fix nothing
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(dirname "$SCRIPT_DIR")"
+cd "$ROOT"
+
+MODE="fix"
+if [ "${1:-}" = "--check" ]; then
+  MODE="check"
+fi
+
+python3 - "$MODE" <<'PYEOF'
+import json
+import re
+import sys
+
+mode = sys.argv[1]
+
+with open("package.json") as f:
+    root_version = json.load(f)["version"]
+
+version_line_re = re.compile(r'^(\s*"version"\s*:\s*)"[^"]*"(,?\s*(?:\r?\n)?)$')
+
+def sync_file(path, mismatches):
+    with open(path) as f:
+        lines = f.readlines()
+    changed = False
+    out = []
+    for line in lines:
+        m = version_line_re.match(line)
+        if m:
+            current = re.search(r'"version"\s*:\s*"([^"]*)"', line).group(1)
+            if current != root_version:
+                mismatches.append((path, current))
+                changed = True
+                line = f'{m.group(1)}"{root_version}"{m.group(2)}'
+        out.append(line)
+    if changed and mode == "fix":
+        with open(path, "w") as f:
+            f.writelines(out)
+    return changed
+
+mismatches = []
+plugin_files = [
+    "plugin/.claude-plugin/plugin.json",
+    "plugin-hooks/.claude-plugin/plugin.json",
+    "plugin-task-loop/.claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+]
+
+for path in plugin_files:
+    sync_file(path, mismatches)
+
+if mode == "check":
+    if mismatches:
+        print(f"Version mismatch: package.json is {root_version}, but found:")
+        for path, version in mismatches:
+            print(f"  {path}: {version}")
+        print("Run ./scripts/sync-plugin-version.sh to fix.")
+        sys.exit(1)
+    print(f"All plugin/marketplace manifests match package.json ({root_version}).")
+else:
+    if mismatches:
+        print(f"Synced {len(mismatches)} version occurrence(s) to {root_version}:")
+        for path, old_version in mismatches:
+            print(f"  {path}: {old_version} -> {root_version}")
+    else:
+        print(f"Already in sync at version {root_version}. No changes made.")
+PYEOF

package/src/main.rs

@@ -1,7 +1,26 @@
 use std::io::{self, BufRead, Write};
+use std::sync::mpsc;
+use std::thread;
+use std::time::Duration;
 
 use handoff_mcp::mcp::protocol::process_line;
 
+/// Maximum time a single JSON-RPC request may take before the server gives
+/// up waiting and returns a fail-safe error response. Processing continues
+/// on the worker thread in the background; the timeout only bounds how long
+/// the main loop blocks waiting for a reply. Override for tests via
+/// `HANDOFF_MCP_REQUEST_TIMEOUT_SECS` (parsed once at startup; falls back to
+/// the 30s default on missing/invalid values).
+const DEFAULT_REQUEST_TIMEOUT_SECS: u64 = 30;
+
+fn request_timeout() -> Duration {
+    let secs = std::env::var("HANDOFF_MCP_REQUEST_TIMEOUT_SECS")
+        .ok()
+        .and_then(|v| v.parse::<u64>().ok())
+        .unwrap_or(DEFAULT_REQUEST_TIMEOUT_SECS);
+    Duration::from_secs(secs)
+}
+
 fn main() {
     let args: Vec<String> = std::env::args().collect();
 
@@ -46,6 +65,7 @@ fn main() {
 
     let stdin = io::stdin();
     let mut stdout = io::stdout();
+    let timeout = request_timeout();
 
     for line in stdin.lock().lines() {
         let line = match line {
@@ -56,12 +76,53 @@ fn main() {
             }
         };
 
-        if let Some(response) = process_line(&line) {
-            if writeln!(stdout, "{response}").is_err() {
-                break;
+        // Run this request on a dedicated worker thread so a slow handler
+        // can't block the main loop forever: `recv_timeout` below bounds how
+        // long we wait for a reply. The next line is only read after this
+        // request's worker completes (or times out) — sequential processing
+        // order is preserved; this is a fail-safe timeout, not parallelism.
+        let (tx, rx) = mpsc::channel();
+        let line_for_worker = line.clone();
+        thread::spawn(move || {
+            let result = process_line(&line_for_worker);
+            let _ = tx.send(result);
+        });
+
+        match rx.recv_timeout(timeout) {
+            Ok(Some(response)) => {
+                if writeln!(stdout, "{response}").is_err() {
+                    break;
+                }
+                if stdout.flush().is_err() {
+                    break;
+                }
             }
-            if stdout.flush().is_err() {
-                break;
+            Ok(None) => {
+                // Notification: no response expected.
+            }
+            Err(mpsc::RecvTimeoutError::Timeout) => {
+                eprintln!("Request timed out after {}s", timeout.as_secs());
+                let id = serde_json::from_str::<serde_json::Value>(&line)
+                    .ok()
+                    .and_then(|req| req.get("id").cloned())
+                    .unwrap_or(serde_json::Value::Null);
+                let error_response = serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": id,
+                    "error": {
+                        "code": -32603,
+                        "message": format!("Request timed out after {}s", timeout.as_secs())
+                    }
+                });
+                if writeln!(stdout, "{error_response}").is_err() {
+                    break;
+                }
+                if stdout.flush().is_err() {
+                    break;
+                }
+            }
+            Err(mpsc::RecvTimeoutError::Disconnected) => {
+                eprintln!("Worker thread disconnected without a response");
             }
         }
     }

package/src/setup.rs

@@ -6,7 +6,6 @@ use serde_json::Value;
 
 const HOOK_SERVER: &str = "handoff";
 const HOOK_TOOL_QUERY: &str = "handoff_memory_query";
-const HOOK_TOOL_CLEANUP: &str = "handoff_memory_cleanup";
 
 fn settings_path() -> Result<PathBuf> {
     let home = std::env::var("HOME")
@@ -77,15 +76,6 @@ fn build_hooks_config() -> BTreeMap<&'static str, Value> {
         }]),
     );
 
-    hooks.insert(
-        "SessionStart",
-        serde_json::json!([{
-            "hooks": [mcp_tool_hook(HOOK_TOOL_CLEANUP, serde_json::json!({
-                "project_dir": "${CLAUDE_PROJECT_DIR}"
-            }))]
-        }]),
-    );
-
     hooks
 }
 
@@ -106,6 +96,54 @@ fn has_handoff_hook(arr: &Value) -> bool {
     false
 }
 
+/// Legacy event that used to carry a synchronous `handoff_memory_cleanup`
+/// hook. Removed as a desired hook in this fix (see wiki/100-stdio-concurrency.md)
+/// because it was the trigger for the VSCode hang under many parallel
+/// sub-agents. Still used to detect and migrate away stale installs from
+/// before this fix.
+const LEGACY_SESSION_START_EVENT: &str = "SessionStart";
+
+/// True if `settings` still has a handoff-owned hook registered under the
+/// legacy `SessionStart` event (i.e. an install performed before this fix
+/// removed the synchronous cleanup hook). Used both to auto-migrate on
+/// `setup` re-run and to flag the issue in `setup --check`.
+fn has_legacy_session_start_hook(settings: &Value) -> bool {
+    settings
+        .get("hooks")
+        .and_then(|h| h.get(LEGACY_SESSION_START_EVENT))
+        .map(has_handoff_hook)
+        .unwrap_or(false)
+}
+
+/// Removes handoff-owned hook entries from the legacy `SessionStart` event,
+/// leaving any other (non-handoff) hooks registered under that event intact.
+/// Returns true if anything was removed.
+fn strip_legacy_session_start_hook(hooks_obj: &mut serde_json::Map<String, Value>) -> bool {
+    let Some(arr) = hooks_obj
+        .get_mut(LEGACY_SESSION_START_EVENT)
+        .and_then(|v| v.as_array_mut())
+    else {
+        return false;
+    };
+
+    let before = arr.len();
+    arr.retain(|entry| {
+        let Some(hooks) = entry.get("hooks").and_then(|v| v.as_array()) else {
+            return true;
+        };
+        !hooks
+            .iter()
+            .any(|h| h.get("server").and_then(|v| v.as_str()) == Some(HOOK_SERVER))
+    });
+    let removed = arr.len() != before;
+
+    if arr.is_empty() {
+        hooks_obj.remove(LEGACY_SESSION_START_EVENT);
+    }
+
+    removed
+}
+
 pub fn run_setup(check_only: bool, uninstall: bool) -> Result<()> {
     anyhow::ensure!(
         !(check_only && uninstall),
@@ -147,10 +185,22 @@ fn run_check(settings: &Value, path: &Path) -> Result<()> {
         }
     }
 
+    if has_legacy_session_start_hook(settings) {
+        println!(
+            "  {LEGACY_SESSION_START_EVENT}: legacy handoff_memory_cleanup hook found (removed in this version)"
+        );
+        println!(
+            "\nWARNING: a synchronous SessionStart cleanup hook from an older install was \
+             found. This is the known trigger for VSCode hangs under many parallel \
+             sub-agents. Run `handoff-mcp setup` (without --check) to remove it."
+        );
+        all_ok = false;
+    }
+
     if all_ok {
         println!("\nAll hooks are configured. Memory auto-injection is active.");
     } else {
-        println!("\nSome hooks are missing. Run `handoff-mcp setup` to install them.");
+        println!("\nHooks need attention. Run `handoff-mcp setup` to install/migrate them.");
     }
 
     Ok(())
@@ -197,10 +247,28 @@ fn run_install(settings: &mut Value, path: &Path) -> Result<()> {
         installed += 1;
     }
 
-    if installed > 0 {
+    // Migrate away from a pre-fix install: an older `handoff-mcp setup` used
+    // to write a synchronous SessionStart `handoff_memory_cleanup` hook,
+    // which is the confirmed trigger for the VSCode hang under many
+    // parallel sub-agents (wiki/100-stdio-concurrency.md). Strip it here so
+    // that simply re-running `setup` remediates existing installs.
+    let migrated = strip_legacy_session_start_hook(hooks_obj);
+    if migrated {
+        println!(
+            "  {LEGACY_SESSION_START_EVENT}: removed legacy handoff_memory_cleanup hook \
+             (known VSCode hang trigger)"
+        );
+    }
+
+    if installed > 0 || migrated {
         write_settings(path, settings)?;
         println!("\nWrote {path}", path = path.display());
-        println!("{installed} hook(s) installed, {skipped} already present.");
+        if installed > 0 {
+            println!("{installed} hook(s) installed, {skipped} already present.");
+        }
+        if migrated {
+            println!("Legacy SessionStart cleanup hook removed. See README for migration details.");
+        }
         println!("\nRestart Claude Code for hooks to take effect.");
     } else {
         println!("\nAll hooks already installed. Nothing to do.");
@@ -267,12 +335,12 @@ mod tests {
     use super::*;
 
     #[test]
-    fn build_hooks_has_three_events() {
+    fn build_hooks_has_two_events() {
         let hooks = build_hooks_config();
-        assert_eq!(hooks.len(), 3);
+        assert_eq!(hooks.len(), 2);
         assert!(hooks.contains_key("UserPromptSubmit"));
         assert!(hooks.contains_key("PreToolUse"));
-        assert!(hooks.contains_key("SessionStart"));
+        assert!(!hooks.contains_key("SessionStart"));
     }
 
     #[test]
@@ -309,7 +377,7 @@ mod tests {
         let hooks = written.get("hooks").unwrap().as_object().unwrap();
         assert!(hooks.contains_key("UserPromptSubmit"));
         assert!(hooks.contains_key("PreToolUse"));
-        assert!(hooks.contains_key("SessionStart"));
+        assert!(!hooks.contains_key("SessionStart"));
     }
 
     #[test]
@@ -349,6 +417,10 @@ mod tests {
             serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
         let user_prompt = written["hooks"]["UserPromptSubmit"].as_array().unwrap();
         assert_eq!(user_prompt.len(), 1);
+        assert!(!written["hooks"]
+            .as_object()
+            .unwrap()
+            .contains_key("SessionStart"));
     }
 
     #[test]
@@ -400,6 +472,96 @@ mod tests {
         );
     }
 
+    #[test]
+    fn install_removes_legacy_session_start_cleanup_hook() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        // Simulate a settings.json written by a pre-fix version of
+        // `handoff-mcp setup`, which still installed a SessionStart
+        // cleanup hook (the very hang trigger this task removes).
+        let mut settings = serde_json::json!({
+            "hooks": {
+                "SessionStart": [{
+                    "hooks": [{
+                        "type": "mcp_tool",
+                        "server": "handoff",
+                        "tool": "handoff_memory_cleanup",
+                        "input": {"project_dir": "${CLAUDE_PROJECT_DIR}"}
+                    }]
+                }],
+                "UserPromptSubmit": [{
+                    "hooks": [{"type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query"}]
+                }],
+                "PreToolUse": [{
+                    "matcher": "Edit|Write|MultiEdit",
+                    "hooks": [{"type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query"}]
+                }]
+            }
+        });
+
+        run_install(&mut settings, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let hooks = written.get("hooks").unwrap().as_object().unwrap();
+        assert!(
+            !hooks.contains_key("SessionStart"),
+            "legacy SessionStart cleanup hook must be removed by re-running setup"
+        );
+        assert!(hooks.contains_key("UserPromptSubmit"));
+        assert!(hooks.contains_key("PreToolUse"));
+    }
+
+    #[test]
+    fn install_preserves_non_handoff_session_start_hooks() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = serde_json::json!({
+            "hooks": {
+                "SessionStart": [
+                    {"hooks": [{"type": "command", "command": "my-other-hook"}]},
+                    {"hooks": [{"type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_cleanup"}]}
+                ]
+            }
+        });
+
+        run_install(&mut settings, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let session_start = written["hooks"]["SessionStart"].as_array().unwrap();
+        assert_eq!(session_start.len(), 1);
+        assert!(!has_handoff_hook(&written["hooks"]["SessionStart"]));
+    }
+
+    #[test]
+    fn check_flags_legacy_session_start_cleanup_hook() {
+        let settings = serde_json::json!({
+            "hooks": {
+                "SessionStart": [{
+                    "hooks": [{"type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_cleanup"}]
+                }]
+            }
+        });
+
+        assert!(has_legacy_session_start_hook(&settings));
+    }
+
+    #[test]
+    fn check_does_not_flag_when_no_legacy_hook_present() {
+        let settings = serde_json::json!({
+            "hooks": {
+                "UserPromptSubmit": [{
+                    "hooks": [{"type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query"}]
+                }]
+            }
+        });
+
+        assert!(!has_legacy_session_start_hook(&settings));
+    }
+
     #[test]
     fn uninstall_preserves_other_hooks() {
         let dir = tempfile::tempdir().unwrap();