handoff-mcp-server 0.8.0 → 0.10.0

package/Cargo.lock

@@ -144,7 +144,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.8.0"
+version = "0.10.0"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

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

package/README.md

@@ -19,17 +19,17 @@ This gets painful fast on multi-session projects.
 ```
 Session 1                          Session 2
 ┌──────────────┐                   ┌──────────────┐
-│ Working...   │   .handoff/       │ Loading...   │
-│              │──────────────────>│              │
-│ save_context │   tasks/          │ load_context │
-│  - summary   │   sessions/      │  - tasks     │
-│  - decisions │   config.toml    │  - decisions │
-│  - blockers  │                   │  - blockers  │
-│  - tasks     │                   │  - git state │
+│ Working...   │   .handoff/       │ load_context │
+│              │──────────────────>│  ↓ guidance  │
+│ save_context │   tasks/          │ save_context │
+│  - close     │   sessions/      │  (active)    │
+│  - summary   │   config.toml    │  ↓ work...   │
+│  - decisions │                   │ save_context │
+│  - blockers  │                   │  (close)     │
 └──────────────┘                   └──────────────┘
 ```
 
-At session end, the agent calls `handoff_save_context` to persist what matters. At session start, it calls `handoff_load_context` to pick up where things left off.
+At session start, the agent calls `handoff_load_context` to pick up where things left off. If no active session exists, the response includes `session_guidance` prompting the agent to establish one via `handoff_save_context` with `session_status: "active"` — this creates a persistent `.active.json` that survives interruptions. At session end, the agent calls `handoff_save_context` (defaulting to `session_status: "closed"`) to close the session.
 
 ## Installation
 
@@ -92,11 +92,11 @@ Add to your Claude Code MCP configuration:
    └── tasks/           # Task tree (directories + TOML files)
    ```
 
-2. **Work normally** — create tasks, track progress, make decisions.
+2. **Load context** at session start — the agent calls `handoff_load_context`. If `session_guidance` is returned, the agent establishes an active session via `handoff_save_context` with `session_status: "active"` before starting work.
 
-3. **Save context** at session end — the agent captures a summary, decisions, blockers, and references.
+3. **Work normally** — create tasks, track progress, make decisions. The active session persists on disk, so progress survives interruptions.
 
-4. **Load context** at next session start — the agent reads back everything and resumes.
+4. **Save context** at session end — the agent calls `handoff_save_context` to close the active session with handoff data (summary, decisions, blockers, references).
 
 > Add `.handoff/` to your `.gitignore` — it contains local working state, not code.
 
@@ -106,7 +106,7 @@ Add to your Claude Code MCP configuration:
 |------|---------|
 | `handoff_init` | Initialize `.handoff/` directory for a project |
 | `handoff_load_context` | Load session context, tasks, and git state at session start |
-| `handoff_save_context` | Save session summary, decisions, blockers, and references |
+| `handoff_save_context` | Save session state — establish an active session (`session_status: "active"`) or close it (default) with handoff data |
 | `handoff_list_tasks` | List tasks with optional status filter |
 | `handoff_update_task` | Create, update, or move tasks in a hierarchical tree |
 | `handoff_get_config` | Read project configuration |
@@ -201,6 +201,9 @@ This project uses handoff-mcp for session continuity.
 
 - **Session start**: Call `handoff_load_context` to load previous session state.
   If not initialized, call `handoff_init` with the project name.
+  If `session_guidance` is present, immediately call `handoff_save_context`
+  with `session_status: "active"` to establish a persistent session before
+  starting work. Include inherited context from the previous session.
 - **Session end**: Call `handoff_save_context` with a summary, decisions, and blockers.
 - **During work**: Use `handoff_update_task` to track progress.
   Mark tasks `in_progress` when starting, `done` when complete.

package/package.json

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

package/src/mcp/handlers/import_context.rs

@@ -49,6 +49,11 @@ pub fn handle(arguments: &Value) -> Result<String> {
         }
     }
 
+    let skip_session_close = arguments
+        .get("skip_session_close")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+
     let mut session_saved = false;
     if let Some(session) = arguments.get("session") {
         let summary = session
@@ -58,7 +63,9 @@ pub fn handle(arguments: &Value) -> Result<String> {
                 anyhow::anyhow!("'session.summary' is required when session is provided")
             })?;
 
-        close_active_sessions(&sessions_dir)?;
+        if !skip_session_close {
+            close_active_sessions(&sessions_dir)?;
+        }
         let git_state = capture_git_state(&project_dir)?;
         let now = Utc::now().to_rfc3339();
 
@@ -118,7 +125,9 @@ pub fn handle(arguments: &Value) -> Result<String> {
         session_saved = true;
     } else if let Some(raw_notes) = arguments.get("raw_notes").and_then(|v| v.as_str()) {
         if !raw_notes.is_empty() {
-            close_active_sessions(&sessions_dir)?;
+            if !skip_session_close {
+                close_active_sessions(&sessions_dir)?;
+            }
             let git_state = capture_git_state(&project_dir)?;
             let now = Utc::now().to_rfc3339();
 

package/src/mcp/handlers/load_context.rs

@@ -5,10 +5,11 @@ use super::resolve_project_dir;
 use crate::storage::config::read_config;
 use crate::storage::referrals::read_referral_summaries;
 use crate::storage::sessions::{
-    activate_open_sessions, activate_session_by_id, read_active_sessions, read_open_sessions,
-    read_paused_sessions, resume_paused_session_by_id,
+    activate_open_sessions, activate_session_by_id, read_active_sessions,
+    read_latest_closed_session, read_open_sessions, read_paused_sessions,
+    resume_paused_session_by_id,
 };
-use crate::storage::tasks::build_task_index;
+use crate::storage::tasks::{build_task_index, TaskIndex};
 use crate::storage::{ensure_handoff_exists, handoff_dir};
 
 pub fn handle(arguments: &Value) -> Result<String> {
@@ -139,19 +140,63 @@ pub fn handle(arguments: &Value) -> Result<String> {
         }
     }
 
-    if let Some(notes) = result.get("handoff_notes").and_then(|v| v.as_array()) {
-        let suggestions: Vec<&str> = notes
-            .iter()
-            .filter(|n| {
-                n.get("category")
-                    .and_then(|c| c.as_str())
-                    .is_some_and(|c| c == "suggestion")
-            })
-            .filter_map(|n| n.get("note").and_then(|v| v.as_str()))
-            .collect();
-        if !suggestions.is_empty() {
-            result["next_actions"] = serde_json::json!(suggestions);
+    if let Some(prev) = read_latest_closed_session(&sessions_dir)? {
+        let prev_val = serde_json::to_value(&prev).unwrap_or_default();
+        let mut prev_obj = serde_json::json!({
+            "summary": prev.summary,
+            "ended_at": prev.ended_at,
+            "branch": prev.branch,
+            "commit": prev.commit,
+        });
+        if let Some(ref id) = prev.id {
+            prev_obj["id"] = serde_json::json!(id);
+        }
+        for key in [
+            "decisions",
+            "handoff_notes",
+            "context_pointers",
+            "checklist",
+            "references",
+            "blockers",
+        ] {
+            if let Some(val) = prev_val.get(key) {
+                if val.as_array().is_some_and(|a| !a.is_empty()) {
+                    prev_obj[key] = val.clone();
+                }
+            }
         }
+        if let Some(env) = prev_val.get("environment") {
+            if !env.is_null() {
+                prev_obj["environment"] = env.clone();
+            }
+        }
+        result["previous_session"] = prev_obj;
+    }
+
+    let notes_sources: Vec<&Value> = [
+        result.get("handoff_notes"),
+        result
+            .get("previous_session")
+            .and_then(|ps| ps.get("handoff_notes")),
+    ]
+    .into_iter()
+    .flatten()
+    .collect();
+
+    let suggestions: Vec<&str> = notes_sources
+        .iter()
+        .filter_map(|v| v.as_array())
+        .flatten()
+        .filter(|n| {
+            n.get("category")
+                .and_then(|c| c.as_str())
+                .is_some_and(|c| c == "suggestion")
+        })
+        .filter_map(|n| n.get("note").and_then(|v| v.as_str()))
+        .collect();
+
+    if !suggestions.is_empty() {
+        result["next_actions"] = serde_json::json!(suggestions);
     }
 
     if !config.settings.context_files.is_empty() {
@@ -180,5 +225,55 @@ pub fn handle(arguments: &Value) -> Result<String> {
         result["paused_sessions"] = serde_json::json!(summaries);
     }
 
+    let has_active_session = read_active_sessions(&sessions_dir)
+        .map(|s| !s.is_empty())
+        .unwrap_or(false);
+    if !has_active_session {
+        let mut guidance = serde_json::json!({
+            "action": "create_session",
+            "message": "No active session. Before starting work, call handoff_save_context with session_status='active' to establish a session. Include inherited context (decisions, context_pointers, references) from the previous session so your work survives interruptions."
+        });
+        if let Some(prev) = result.get("previous_session") {
+            let mut suggested = serde_json::json!({});
+            if let Some(summary) = prev.get("summary").and_then(|v| v.as_str()) {
+                suggested["summary"] = serde_json::json!(format!("Continuing: {summary}"));
+            }
+            for key in ["decisions", "context_pointers", "references"] {
+                if let Some(val) = prev.get(key) {
+                    if val.as_array().is_some_and(|a| !a.is_empty()) {
+                        suggested[key] = val.clone();
+                    }
+                }
+            }
+            if let Some(task_ids) = collect_active_task_ids(&task_tree) {
+                suggested["related_task_ids"] = serde_json::json!(task_ids);
+            }
+            guidance["suggested_fields"] = suggested;
+        }
+        result["session_guidance"] = guidance;
+    }
+
     serde_json::to_string_pretty(&result).context("Failed to serialize context")
 }
+
+fn collect_active_task_ids(task_tree: &[TaskIndex]) -> Option<Vec<String>> {
+    let mut ids = Vec::new();
+    collect_active_ids_recursive(task_tree, &mut ids);
+    if ids.is_empty() {
+        None
+    } else {
+        Some(ids)
+    }
+}
+
+fn collect_active_ids_recursive(tasks: &[TaskIndex], ids: &mut Vec<String>) {
+    for task in tasks {
+        if matches!(
+            task.status.as_str(),
+            "in_progress" | "blocked" | "todo" | "review"
+        ) {
+            ids.push(task.id.clone());
+        }
+        collect_active_ids_recursive(&task.children, ids);
+    }
+}

package/src/mcp/handlers/mod.rs

@@ -9,6 +9,7 @@ pub mod load_context;
 pub mod refer;
 pub mod referrals;
 pub mod save_context;
+pub mod update_session;
 pub mod update_task;
 
 use std::path::PathBuf;
@@ -42,6 +43,7 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_refer" => refer::handle(arguments),
         "handoff_list_referrals" => referrals::handle_list(arguments),
         "handoff_update_referral" => referrals::handle_update(arguments),
+        "handoff_update_session" => update_session::handle(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };
 

package/src/mcp/handlers/save_context.rs

@@ -9,9 +9,9 @@ use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::git::capture_git_state;
 use crate::storage::sessions::{
-    close_active_sessions, close_session_by_id, enforce_history_limit, generate_session_id,
-    pause_active_sessions, pause_session_by_id, read_active_sessions, write_session_with_status,
-    SessionData,
+    close_session_by_id, enforce_history_limit, generate_session_id, pause_active_sessions,
+    pause_session_by_id, read_active_sessions, update_active_session,
+    update_and_close_active_session, write_session_with_status, SessionData,
 };
 
 pub fn handle(arguments: &Value) -> Result<String> {
@@ -21,29 +21,25 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let sessions_dir = handoff.join("sessions");
     let config_path = handoff.join("config.toml");
 
-    let summary = arguments
-        .get("summary")
-        .and_then(|v| v.as_str())
-        .ok_or_else(|| anyhow::anyhow!("'summary' is required"))?;
-
     let close_id = arguments.get("close_session_id").and_then(|v| v.as_str());
     let pause_id = arguments.get("pause_session_id").and_then(|v| v.as_str());
     let pause_all = arguments
         .get("pause_active")
         .and_then(|v| v.as_bool())
         .unwrap_or(false);
-    let session_status = arguments
-        .get("session_status")
-        .and_then(|v| v.as_str())
-        .unwrap_or("open");
+    let is_pause_only = arguments
+        .get("pause_only")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
 
-    if session_status != "open" && session_status != "active" {
-        anyhow::bail!(
-            "Invalid session_status '{}': must be 'open' or 'active'",
-            session_status
-        );
+    let summary_opt = arguments.get("summary").and_then(|v| v.as_str());
+
+    if !is_pause_only && summary_opt.is_none() {
+        anyhow::bail!("'summary' is required (unless pause_only=true)");
     }
 
+    let summary = summary_opt.unwrap_or("");
+
     let mut total_paused = 0usize;
     if let Some(id) = pause_id {
         if pause_session_by_id(&sessions_dir, id)?.is_some() {
@@ -53,37 +49,39 @@ pub fn handle(arguments: &Value) -> Result<String> {
         total_paused = pause_active_sessions(&sessions_dir)?.len();
     }
 
-    let total_closed = if let Some(id) = close_id {
-        let closed = close_session_by_id(&sessions_dir, id)?;
-        if closed.is_some() {
-            1
-        } else {
-            0
+    if is_pause_only {
+        let mut msg = String::new();
+        if total_paused > 0 {
+            msg.push_str(&format!("Paused {} session(s)", total_paused));
         }
-    } else if pause_id.is_some() || pause_all {
-        0
-    } else {
-        let active = read_active_sessions(&sessions_dir)?;
-        if active.len() > 1 {
-            let active_ids: Vec<String> = active.iter().filter_map(|s| s.id.clone()).collect();
-            anyhow::bail!(
-                "Multiple active sessions found ({}).\n\
-                 Use close_session_id or pause_session_id to specify which to \
-                 close/pause before saving a new session.",
-                active_ids.join(", ")
-            );
+        if let Some(id) = pause_id {
+            if total_paused == 0 {
+                msg.push_str(&format!(
+                    "Warning: pause_session_id '{id}' not found among active/open sessions"
+                ));
+            }
         }
-        let closed_active = close_active_sessions(&sessions_dir)?;
-        closed_active.len()
-    };
+        if !pause_all && pause_id.is_none() {
+            msg.push_str("Warning: pause_only=true requires pause_session_id or pause_active=true");
+        }
+        if msg.is_empty() {
+            msg.push_str("No sessions were paused (none active)");
+        }
+        return Ok(msg);
+    }
+
+    let session_status = arguments
+        .get("session_status")
+        .and_then(|v| v.as_str())
+        .unwrap_or("closed");
+    let keep_active = session_status == "active";
 
     let git_state = capture_git_state(&project_dir)?;
     let now = Utc::now().to_rfc3339();
-    let session_id = generate_session_id();
 
-    let data = SessionData {
+    let handoff_updates = SessionData {
         version: 2,
-        id: Some(session_id.clone()),
+        id: None,
         ended_at: Some(now),
         summary: summary.to_string(),
         branch: Some(git_state.branch),
@@ -98,7 +96,45 @@ pub fn handle(arguments: &Value) -> Result<String> {
         environment: arguments.get("environment").cloned(),
     };
 
-    let path = write_session_with_status(&sessions_dir, &data, session_status)?;
+    let (total_closed, path, session_id) = if let Some(id) = close_id {
+        let closed = close_session_by_id(&sessions_dir, id)?;
+        (if closed.is_some() { 1 } else { 0 }, None, None)
+    } else if pause_id.is_some() || pause_all {
+        (0, None, None)
+    } else {
+        let active = read_active_sessions(&sessions_dir)?;
+        if active.len() > 1 {
+            let active_ids: Vec<String> = active.iter().filter_map(|s| s.id.clone()).collect();
+            anyhow::bail!(
+                "Multiple active sessions found ({}).\n\
+                 Use close_session_id or pause_session_id to specify which to \
+                 close/pause before saving context.",
+                active_ids.join(", ")
+            );
+        }
+        if let Some(active_session) = active.first() {
+            let sid = active_session.id.clone().unwrap_or_default();
+            if keep_active {
+                let updated_path = update_active_session(&sessions_dir, &sid, &handoff_updates)?;
+                (0, updated_path, Some(sid))
+            } else {
+                let closed_path =
+                    update_and_close_active_session(&sessions_dir, &sid, &handoff_updates)?;
+                (
+                    if closed_path.is_some() { 1 } else { 0 },
+                    closed_path,
+                    Some(sid),
+                )
+            }
+        } else {
+            let new_id = generate_session_id();
+            let mut data = handoff_updates.clone();
+            data.id = Some(new_id.clone());
+            let target_status = if keep_active { "active" } else { "closed" };
+            let p = write_session_with_status(&sessions_dir, &data, target_status)?;
+            (0, Some(p), Some(new_id))
+        }
+    };
 
     let history_limit = if config_path.exists() {
         read_config(&config_path)
@@ -109,22 +145,28 @@ pub fn handle(arguments: &Value) -> Result<String> {
     };
     let removed = enforce_history_limit(&sessions_dir, history_limit)?;
 
+    let file_display = path
+        .as_ref()
+        .and_then(|p| p.file_name())
+        .map(|n| n.to_string_lossy().to_string())
+        .unwrap_or_else(|| "(none)".to_string());
+    let sid_display = session_id.as_deref().unwrap_or("(no active session)");
     let mut msg = format!(
         "Session saved: {}\nSession ID: {}\nFile: {}",
-        summary,
-        session_id,
-        path.file_name()
-            .map(|n| n.to_string_lossy().to_string())
-            .unwrap_or_default()
+        summary, sid_display, file_display
     );
 
+    if keep_active {
+        msg.push_str("\nSession kept active (session_status: active)");
+    }
+
     if total_paused > 0 {
         msg.push_str(&format!("\nPaused {} session(s)", total_paused));
     }
     if let Some(id) = pause_id {
         if total_paused == 0 {
             msg.push_str(&format!(
-                "\nWarning: pause_session_id '{id}' not found among active sessions"
+                "\nWarning: pause_session_id '{id}' not found among active/open sessions"
             ));
         }
     }
@@ -144,7 +186,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
         ));
     }
 
-    for w in collect_save_warnings(&data, &project_dir) {
+    for w in collect_save_warnings(&handoff_updates, &project_dir) {
         msg.push_str(&format!("\n{w}"));
     }
 

package/src/mcp/handlers/update_session.rs

@@ -0,0 +1,188 @@
+use anyhow::{Context, Result};
+use serde_json::Value;
+
+use super::resolve_project_dir;
+use crate::storage::ensure_handoff_exists;
+use crate::storage::sessions::{read_active_sessions, SessionData};
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let sessions_dir = handoff.join("sessions");
+
+    let active = read_active_sessions(&sessions_dir)?;
+    if active.is_empty() {
+        anyhow::bail!(
+            "No active session. Call save_context with session_status='active' to create one first."
+        );
+    }
+    if active.len() > 1 {
+        let ids: Vec<String> = active.iter().filter_map(|s| s.id.clone()).collect();
+        anyhow::bail!(
+            "Multiple active sessions ({}). Use save_context to resolve.",
+            ids.join(", ")
+        );
+    }
+
+    let session = &active[0];
+    let sid = session.id.as_deref().unwrap_or("");
+
+    let checklist_index = arguments
+        .get("checklist_index")
+        .and_then(|v| v.as_u64())
+        .map(|v| v as usize);
+    let checklist_checked = arguments.get("checklist_checked").and_then(|v| v.as_bool());
+    let add_checklist_item = arguments.get("add_checklist_item").and_then(|v| v.as_str());
+    let add_decision = arguments.get("add_decision");
+    let add_handoff_note = arguments.get("add_handoff_note");
+    let add_context_pointer = arguments.get("add_context_pointer");
+
+    let mut data = session.clone();
+    let mut changes = Vec::new();
+
+    if let Some(idx) = checklist_index {
+        let checked = checklist_checked.unwrap_or(true);
+        if idx >= data.checklist.len() {
+            anyhow::bail!(
+                "checklist_index {idx} out of range (session has {} items)",
+                data.checklist.len()
+            );
+        }
+        if let Some(item) = data.checklist.get_mut(idx) {
+            item["checked"] = serde_json::json!(checked);
+            let item_text = item
+                .get("item")
+                .and_then(|v| v.as_str())
+                .unwrap_or("(unknown)");
+            changes.push(format!(
+                "checklist[{idx}] '{}' → {}",
+                item_text,
+                if checked { "checked" } else { "unchecked" }
+            ));
+        }
+    }
+
+    if let Some(item_text) = add_checklist_item {
+        let owner = arguments
+            .get("checklist_owner")
+            .and_then(|v| v.as_str())
+            .unwrap_or("ai");
+        data.checklist.push(serde_json::json!({
+            "item": item_text,
+            "checked": false,
+            "owner": owner
+        }));
+        changes.push(format!("added checklist item: '{item_text}'"));
+    }
+
+    if let Some(decision) = add_decision {
+        if decision.is_object() {
+            data.decisions.push(decision.clone());
+            let desc = decision
+                .get("decision")
+                .and_then(|v| v.as_str())
+                .unwrap_or("(decision)");
+            changes.push(format!("added decision: '{desc}'"));
+        } else {
+            anyhow::bail!("add_decision must be an object with at least a 'decision' field");
+        }
+    }
+
+    if let Some(note) = add_handoff_note {
+        if note.is_object() {
+            data.handoff_notes.push(note.clone());
+            let text = note
+                .get("note")
+                .and_then(|v| v.as_str())
+                .unwrap_or("(note)");
+            changes.push(format!("added handoff_note: '{}'", truncate(text, 60)));
+        } else {
+            anyhow::bail!("add_handoff_note must be an object with at least a 'note' field");
+        }
+    }
+
+    if let Some(pointer) = add_context_pointer {
+        if pointer.is_object() {
+            data.context_pointers.push(pointer.clone());
+            let path = pointer
+                .get("path")
+                .and_then(|v| v.as_str())
+                .unwrap_or("(path)");
+            changes.push(format!("added context_pointer: '{path}'"));
+        } else {
+            anyhow::bail!("add_context_pointer must be an object with at least a 'path' field");
+        }
+    }
+
+    if changes.is_empty() {
+        anyhow::bail!(
+            "No updates specified. Use checklist_index, add_checklist_item, \
+             add_decision, add_handoff_note, or add_context_pointer."
+        );
+    }
+
+    write_active_session_data(&sessions_dir, sid, &data)?;
+
+    let mut msg = format!("Session {} updated:", sid);
+    for c in &changes {
+        msg.push_str(&format!("\n  - {c}"));
+    }
+
+    let checked_count = data
+        .checklist
+        .iter()
+        .filter(|item| {
+            item.get("checked")
+                .and_then(|v| v.as_bool())
+                .unwrap_or(false)
+        })
+        .count();
+    msg.push_str(&format!(
+        "\nChecklist: {}/{} checked",
+        checked_count,
+        data.checklist.len()
+    ));
+
+    Ok(msg)
+}
+
+fn truncate(s: &str, max: usize) -> String {
+    if s.len() <= max {
+        s.to_string()
+    } else {
+        format!("{}...", &s[..max])
+    }
+}
+
+fn write_active_session_data(
+    sessions_dir: &std::path::Path,
+    session_id: &str,
+    data: &SessionData,
+) -> Result<()> {
+    let suffix = ".active.json";
+
+    for entry in std::fs::read_dir(sessions_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if !name.ends_with(suffix) {
+            continue;
+        }
+
+        let content = std::fs::read_to_string(entry.path())
+            .with_context(|| format!("Failed to read session: {}", entry.path().display()))?;
+        let existing: SessionData = serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse session: {}", entry.path().display()))?;
+
+        let file_id = existing.id.as_deref().unwrap_or("");
+        if file_id != session_id {
+            continue;
+        }
+
+        let updated = serde_json::to_string_pretty(data).context("Failed to serialize session")?;
+        std::fs::write(entry.path(), updated)
+            .with_context(|| format!("Failed to write session: {}", entry.path().display()))?;
+        return Ok(());
+    }
+
+    anyhow::bail!("Active session '{session_id}' not found on disk")
+}

package/src/mcp/router.rs

@@ -48,18 +48,22 @@ fn handle_initialize() -> JsonRpcResponse {
              ## Session Start\n\
              1. Call handoff_load_context (no args needed — uses cwd)\n\
              2. If it returns \"not initialized\", call handoff_init with the project name\n\
-             3. Check the `next_actions` array first — these are the previous session's recommended next steps. Do not re-verify work the previous session already completed\n\n\
+             3. If session_guidance is present, call handoff_save_context with session_status='active' to establish a persistent session before starting work\n\
+             4. Check the `next_actions` array first — these are the previous session's recommended next steps. Do not re-verify work the previous session already completed\n\n\
+             ## During Work — Progressive Updates\n\
+             - Use handoff_update_task to create/update tasks as work progresses\n\
+             - Mark tasks in_progress when starting, done when complete\n\
+             - Use handoff_check_criterion to check off task done_criteria as each item is verified — do not wait until the task is fully done\n\
+             - Use handoff_update_session to progressively update the active session: toggle checklist items, append decisions, notes, or context pointers\n\
+             - When work reaches a point requiring user confirmation, set the task status to review\n\
+             - Record decisions as they are made, not just at session end\n\n\
              ## Session End\n\
              1. Call handoff_save_context with:\n\
                 - summary: one-line description of what was accomplished\n\
                 - decisions: key decisions made (with reason and confidence)\n\
                 - blockers: anything preventing progress\n\
                 - handoff_notes: caution/context/suggestion for the next session\n\
-                - context_pointers: files and line ranges the next session should look at\n\n\
-             ## During Work\n\
-             - Use handoff_update_task to create/update tasks as work progresses\n\
-             - Mark tasks in_progress when starting, done when complete\n\
-             - Record decisions as they are made, not just at session end"
+                - context_pointers: files and line ranges the next session should look at"
                 .to_string(),
         ),
     };

package/src/mcp/tools.rs

@@ -59,9 +59,9 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "session_status": {
                         "type": "string",
-                        "description": "Status of the new session: 'open' (default) = saved but not activated, allows multiple open sessions; 'active' = immediately active for this session.",
-                        "enum": ["open", "active"],
-                        "default": "open"
+                        "description": "Session status after save. 'closed' (default) = close the active session as history. 'active' = keep or create an active session (use at session start to establish a persistent session that survives interruptions).",
+                        "enum": ["closed", "active"],
+                        "default": "closed"
                     },
                     "close_session_id": {
                         "type": "string",
@@ -75,6 +75,10 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "type": "boolean",
                         "description": "If true, pause all active sessions instead of closing them. Cannot be combined with close_session_id."
                     },
+                    "pause_only": {
+                        "type": "boolean",
+                        "description": "If true, only pause sessions (via pause_session_id or pause_active) without creating a new session. Useful for session switching. When true, summary is optional."
+                    },
                     "decisions": {
                         "type": "array",
                         "description": "Decisions made during this session",
@@ -479,6 +483,10 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "raw_notes": {
                         "type": "string",
                         "description": "Free-form text that couldn't be structured. Saved as a handoff_note with category 'context'."
+                    },
+                    "skip_session_close": {
+                        "type": "boolean",
+                        "description": "If true, do not close active sessions before creating the import session. Default false."
                     }
                 },
                 "required": ["source"],
@@ -636,6 +644,65 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 "required": ["referral_id", "status"]
             }),
         },
+        ToolDefinition {
+            name: "handoff_update_session".to_string(),
+            description: "Incrementally update the active session. Toggle checklist items, add decisions, notes, or context pointers without resending everything. Use during work for progressive updates.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "checklist_index": {
+                        "type": "integer",
+                        "description": "0-based index of a checklist item to toggle."
+                    },
+                    "checklist_checked": {
+                        "type": "boolean",
+                        "description": "Set the checklist item to checked (true) or unchecked (false). Defaults to true."
+                    },
+                    "add_checklist_item": {
+                        "type": "string",
+                        "description": "Text of a new checklist item to add (unchecked)."
+                    },
+                    "checklist_owner": {
+                        "type": "string",
+                        "description": "Owner for the new checklist item: 'user' or 'ai'. Defaults to 'ai'.",
+                        "enum": ["user", "ai"]
+                    },
+                    "add_decision": {
+                        "type": "object",
+                        "description": "A decision to append to the session.",
+                        "properties": {
+                            "decision": { "type": "string" },
+                            "reason": { "type": "string" },
+                            "confidence": { "type": "string", "enum": ["confirmed", "estimated", "unverified"] }
+                        },
+                        "required": ["decision"]
+                    },
+                    "add_handoff_note": {
+                        "type": "object",
+                        "description": "A handoff note to append to the session.",
+                        "properties": {
+                            "note": { "type": "string" },
+                            "category": { "type": "string", "enum": ["caution", "context", "suggestion"] }
+                        },
+                        "required": ["note"]
+                    },
+                    "add_context_pointer": {
+                        "type": "object",
+                        "description": "A context pointer to append to the session.",
+                        "properties": {
+                            "path": { "type": "string" },
+                            "reason": { "type": "string" },
+                            "lines": { "type": "string" }
+                        },
+                        "required": ["path"]
+                    }
+                }
+            }),
+        },
     ]
 }
 

package/src/storage/sessions.rs

@@ -273,7 +273,10 @@ pub fn pause_active_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
 }
 
 pub fn pause_session_by_id(sessions_dir: &Path, session_id: &str) -> Result<Option<PathBuf>> {
-    transition_session_by_id(sessions_dir, session_id, "active", "paused")
+    if let Some(path) = transition_session_by_id(sessions_dir, session_id, "active", "paused")? {
+        return Ok(Some(path));
+    }
+    transition_session_by_id(sessions_dir, session_id, "open", "paused")
 }
 
 pub fn resume_paused_session_by_id(
@@ -291,6 +294,106 @@ pub fn close_paused_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
     transition_sessions(sessions_dir, "paused", "closed")
 }
 
+pub fn read_latest_closed_session(sessions_dir: &Path) -> Result<Option<SessionData>> {
+    let mut sessions = read_sessions_by_status(sessions_dir, "closed")?;
+    sessions.sort_by(|a, b| a.ended_at.cmp(&b.ended_at));
+    Ok(sessions.into_iter().last())
+}
+
+fn apply_session_updates(data: &mut SessionData, updates: &SessionData) {
+    data.summary = updates.summary.clone();
+    data.ended_at = updates.ended_at.clone();
+    data.branch = updates.branch.clone();
+    data.commit = updates.commit.clone();
+    data.dirty_files = updates.dirty_files.clone();
+    data.decisions = updates.decisions.clone();
+    data.blockers = updates.blockers.clone();
+    data.checklist = updates.checklist.clone();
+    data.handoff_notes = updates.handoff_notes.clone();
+    data.references = updates.references.clone();
+    data.context_pointers = updates.context_pointers.clone();
+    if updates.environment.is_some() {
+        data.environment = updates.environment.clone();
+    }
+}
+
+fn find_and_update_active_session(
+    sessions_dir: &Path,
+    session_id: &str,
+    updates: &SessionData,
+    transition_to: Option<&str>,
+) -> Result<Option<PathBuf>> {
+    let suffix = ".active.json";
+
+    if !sessions_dir.exists() {
+        return Ok(None);
+    }
+
+    for entry in std::fs::read_dir(sessions_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if !name.ends_with(suffix) {
+            continue;
+        }
+
+        let content = std::fs::read_to_string(entry.path())
+            .with_context(|| format!("Failed to read session: {}", entry.path().display()))?;
+        let mut data: SessionData = serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse session: {}", entry.path().display()))?;
+
+        let file_id = data.id.as_deref().unwrap_or("").to_string();
+        let synthesized = if file_id.is_empty() {
+            synthesize_id_from_filename(&name)
+        } else {
+            file_id
+        };
+
+        if synthesized != session_id {
+            continue;
+        }
+
+        apply_session_updates(&mut data, updates);
+
+        let updated_content =
+            serde_json::to_string_pretty(&data).context("Failed to serialize session")?;
+        std::fs::write(entry.path(), &updated_content)
+            .with_context(|| format!("Failed to write session: {}", entry.path().display()))?;
+
+        if let Some(target_status) = transition_to {
+            let target_suffix = format!(".{target_status}.json");
+            let new_name = name.replace(suffix, &target_suffix);
+            let new_path = sessions_dir.join(&new_name);
+            std::fs::rename(entry.path(), &new_path).with_context(|| {
+                format!(
+                    "Failed to transition session active->{target_status}: {}",
+                    entry.path().display()
+                )
+            })?;
+            return Ok(Some(new_path));
+        }
+
+        return Ok(Some(entry.path()));
+    }
+
+    Ok(None)
+}
+
+pub fn update_and_close_active_session(
+    sessions_dir: &Path,
+    session_id: &str,
+    updates: &SessionData,
+) -> Result<Option<PathBuf>> {
+    find_and_update_active_session(sessions_dir, session_id, updates, Some("closed"))
+}
+
+pub fn update_active_session(
+    sessions_dir: &Path,
+    session_id: &str,
+    updates: &SessionData,
+) -> Result<Option<PathBuf>> {
+    find_and_update_active_session(sessions_dir, session_id, updates, None)
+}
+
 pub fn enforce_history_limit(sessions_dir: &Path, limit: u32) -> Result<u32> {
     if !sessions_dir.exists() {
         return Ok(0);