claude-code-infinite 1.0.32 → 1.0.34

package/dist/memtree-mcp.js

@@ -18,8 +18,9 @@
  * tree the current request was compressed against. The session id is the
  * `CLAUDE_CODE_SESSION_ID` Claude Code sets for MCP servers. Reads of this
  * session's current tree require that exact session on both the proxy's pointer
- * and the page; missing or mismatched identity fails closed, and the host must
- * restart this server with the current id when switching sessions. The page JSON
+ * and the page; missing or mismatched identity fails closed. Claude Code does not
+ * restart this server when its process switches sessions, so each tool call first
+ * asks the proxy which session that process is on (`refreshHostSession`). The page JSON
  * is fetched through the proxy's key-free `/memtree/<id>.json` relay and cached
  * once complete.
  *
@@ -32,11 +33,14 @@
  * and falls back to searching the page JSON locally on a server without that
  * endpoint.
  */
+import { HOST_TOKEN_ENV, HOST_TOKEN_HEADER } from "./host-session.js";
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
-import { FINDER_SEARCH_DEFAULT_LIMIT, FINDER_SEARCH_MAX_LIMIT, formatSearchResults, searchMode, formatSessions, searchQuery, SESSIONS_DEFAULT_LIMIT, SESSIONS_MAX_LIMIT, sessionsQuery, } from "./memtree-finder.js";
+import { FINDER_SEARCH_DEFAULT_LIMIT, FINDER_SEARCH_MAX_LIMIT, formatSearchResults, searchMode, formatSessions, RECENT_SEARCH_WINDOWS_DAYS, recentSearchArgs, recentSearchFailedNote, recentSearchNote, searchQuery, SESSIONS_DEFAULT_LIMIT, SESSIONS_MAX_LIMIT, sessionsQuery, } from "./memtree-finder.js";
 import { formatLines, formatNode, formatSearch, formatSearchHits, formatTail, MemtreeIndex, parseNodeAddress, serverSearchHits, serverTailHits, READ_LINES_MAX_CHARS, READ_LINES_MAX_LINES, SEARCH_DEFAULT_LIMIT, SEARCH_MAX_LIMIT, ToolInputError, } from "./memtree-tools.js";
 import { CLIENT_VERSION } from "./memtree.js";
+import { formatHandover, formatUserMessages, HANDOVER_DEFAULT_DAYS, HANDOVER_MAX_DAYS, handoverQuery, USER_MESSAGES_MAX_LIMIT, userMessagesQuery, } from "./memtree-handover.js";
+import { formatTime } from "./memtree-times.js";
 export const MEMTREE_MCP_SERVER_NAME = "memtree";
 /**
  * The version of the ccc whose proxy this server talks to, set in the config
@@ -54,17 +58,71 @@ export function versionMismatchNote(proxyVersion, ownVersion = CLIENT_VERSION) {
     const safe = proxyVersion.replace(/[^0-9A-Za-z.+-]/g, "").slice(0, 40);
     return `(These MemTree tools are ccc ${ownVersion} but this session runs ccc ${safe}: ccc was updated during the session. Restart ccc to use one version.)`;
 }
+/** How often a tool call may re-read the installed package.json (StaleToolsNotice). */
+const STALE_CHECK_INTERVAL_MS = 60_000;
+/**
+ * Says once per session, after a tool's answer, that ccc was updated on disk since
+ * this server started: Claude Code keeps an MCP server for the whole session, so
+ * the tools stay the version it loaded (an older one may lack message times) until
+ * ccc restarts. Silent when the versions match or package.json is unreadable.
+ */
+export class StaleToolsNotice {
+    readInstalled;
+    own;
+    now;
+    startedAt;
+    said = false;
+    checkedAt = -Infinity;
+    constructor(readInstalled = installedVersion, own = CLIENT_VERSION, now = Date.now, startedAt = new Date()) {
+        this.readInstalled = readInstalled;
+        this.own = own;
+        this.now = now;
+        this.startedAt = startedAt;
+    }
+    next() {
+        if (this.said || this.now() - this.checkedAt < STALE_CHECK_INTERVAL_MS)
+            return undefined;
+        this.checkedAt = this.now();
+        const installed = this.readInstalled();
+        if (!installed || installed === this.own)
+            return undefined;
+        this.said = true;
+        return staleToolsNote(installed, this.own, this.startedAt);
+    }
+}
+export function staleToolsNote(installed, own, startedAt) {
+    const safe = installed.replace(/[^0-9A-Za-z.+-]/g, "").slice(0, 40);
+    const loaded = formatTime(startedAt.toISOString());
+    return `(These MemTree tools are ccc ${own}${loaded ? `, loaded ${loaded}` : ""}; ccc ${safe} is installed: restart ccc to use its newer MemTree tools.)`;
+}
+/** The version in this install's package.json now (ccc may have been updated since it started). */
+export function installedVersion() {
+    try {
+        const version = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version;
+        return typeof version === "string" ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Sent to MemTree as `x-memtree-tools` when this server is configured. */
 export const MEMTREE_TOOL_NAMES = [
     "search",
     "read_node",
     "read_lines",
     "list",
+    "user_messages",
+    "handover",
 ];
 /** `tree` value naming this session's own current tree. */
 export const CURRENT_TREE = "current";
 const LATEST_PROTOCOL_VERSION = "2025-06-18";
 const FETCH_TIMEOUT_MS = 60_000;
+/**
+ * A handover pack's first build runs a model call on the server (up to 90 s, plus loading
+ * the tree): wait longer for it. Past this, the server still finishes and caches the pack.
+ */
+const HANDOVER_TIMEOUT_MS = 150_000;
 const PREFIX_RETRY_INTERVAL_MS = 45_000;
 /**
  * The MCP server's instructions, which Claude Code places in the system prompt
@@ -92,16 +150,20 @@ export const MEMTREE_MCP_INSTRUCTIONS = "This session runs in Claude Code Infini
     "and failed), search MemTree before re-deriving it from the code or guessing. The code shows what exists; the " +
     "memory shows what was decided and why. Read the exact lines (read_lines) when precision matters.\n\n" +
     "search with \"tree\": \"current\" looks in this session's MemTree; without tree it searches all of the user's " +
-    "sessions, and list shows those " +
-    "sessions by time and project. Text mode (default, free) matches exact words, ids and paths; vector mode matches " +
-    "meaning: its first page is charged even when the query embedding is cached; cursor continuation is free, " +
-    "including when the embedding must be regenerated. Hits may include an address (<tree>#<node>) and its path from the root. If the address is unavailable, read_lines with the hit’s tree.ref and range reads its exact lines. With an address: " +
+    "ccc sessions on any machine (not Codex or plain claude sessions), and list shows those sessions by time and " +
+    "project. Text mode (default) matches exact words, ids and paths; vector mode matches meaning. A search costs " +
+    "$0.0005 either way: its first page is charged even when cached; cursor continuation is free, even if " +
+    "re-embedded, as is a text search of one tree. Hits may include an address (<tree>#<node>) and its path from the root. If the address is unavailable, read_lines with the hit’s tree.ref and range reads its exact lines. With an address: " +
     "read_node {\"node\": address} opens it with its children, and the path's addresses lead to its parent and " +
     "siblings; read_lines {\"node\": address} reads a leaf's exact lines. Cursors page over live results, not a " +
     "frozen snapshot. A tree trails its conversation: the newest messages (often how a session ended) are in no tree " +
     "yet. A text search of one tree also matches them (listed after the tree's hits), list shows how each session " +
     "ended, and read_lines {\"tail\": true} reads them (with tree for another session's page; large tool calls are " +
-    "shortened, \"full\": true reads them whole).";
+    "shortened, \"full\": true reads them whole).\n\n" +
+    "To take over another session's work, call handover with its session id first; user_messages lists only the " +
+    "person's own messages over a time range.\n\n" +
+    "A hand-off or kickoff prompt you write for another agent or machine names this session's id and MemTree link " +
+    "(list marks this session), so that agent can read this work with list, search and read_node.";
 const TREE_DESC = "A tree reference from list or search (keep its style and own/served suffix; legacy request ids work), or \"current\" for this session's tree.";
 /**
  * Claude Code's per-tool key (2.1.296): the tool is in the prompt from the
@@ -123,13 +185,14 @@ export const MEMTREE_TOOLS = [
         name: "search",
         description: "Find what this conversation doesn't show: exact details from earlier in this session that the memory only " +
             "summarizes, or earlier work from the user's other sessions. Search one tree (tree, \"current\" for this session) " +
-            "or, without tree, all of the user's sessions. Use it before re-deriving or guessing something from earlier work. " +
-            "mode \"text\" (default, free) matches words, ids, paths and errors (in one tree: node summaries and transcript " +
-            "lines); mode \"vector\" matches meaning, ranked per embedding model; its first page is charged even when the " +
-            "query embedding is cached, and cursor continuation is free. Cursors page over live results, not a frozen snapshot. " +
+            "or, without tree, all of the user's ccc sessions on any machine (not Codex or plain claude sessions). " +
+            "Use it before re-deriving or guessing something from earlier work. " +
+            "mode \"text\" (default) matches words, ids, paths and errors (in one tree: node summaries and transcript " +
+            "lines); mode \"vector\" matches meaning, ranked per embedding model. A search costs $0.0005 either way: its " +
+            "first page is charged even when cached; cursor continuation and a text search of one tree are free. Cursors page over live results, not a frozen snapshot. " +
             "Hits include a snippet and range; their node address (<tree>#<node>) and path may be unavailable. Without an address, use read_lines with the hit’s tree.ref and range. " +
             "A text search of one tree also lists matching newest messages no tree covers yet (read them with read_lines tail). " +
-            "Results show when the messages were written (per transcript block). " +
+            "Results show when the messages were written, each matched line its own message's time where recorded. " +
             // Live on every request, unlike the server instructions and Claude Code's
             // deferred-tools list, which a resumed session keeps from its first day.
             MEMTREE_LOADED_NOTE,
@@ -138,7 +201,7 @@ export const MEMTREE_TOOLS = [
             properties: {
                 query: { type: "string", description: "Distinctive words (text; \"quoted phrase\", or, -word across sessions) or a question (vector)." },
                 tree: { type: "string", description: `Optional. ${TREE_DESC} Omit to search all sessions.` },
-                mode: { type: "string", enum: ["text", "vector"], description: "text (default, exact words, free) or vector (meaning, first page charged)." },
+                mode: { type: "string", enum: ["text", "vector"], description: "text (default, exact words) or vector (meaning); first page charged, except text in one tree." },
                 project: { type: "string", description: "Without tree: only sessions in this working directory or git repository (owner/repo, or just repo)." },
                 since: { type: "string", description: "Without tree: only requests at or after this ISO 8601 time or date." },
                 until: { type: "string", description: "Without tree: only requests before this ISO 8601 time or date." },
@@ -152,7 +215,7 @@ export const MEMTREE_TOOLS = [
         name: "read_node",
         description: "Read one MemTree node: its summary, its path from the root (ancestor summaries), its children (id, summary, leaf or branch) and, " +
             "for a leaf, the transcript line range it covers. Give node (an address from search) or id (0 is the root) with an optional tree. " +
-            "Results show when the messages were written (per transcript block).",
+            "Results show when the messages were written (a leaf: its own messages, where recorded).",
         inputSchema: {
             type: "object",
             properties: {
@@ -169,7 +232,7 @@ export const MEMTREE_TOOLS = [
             "With tail: true, read the messages after the tree that no tree covers yet (the end of a session usually is there): " +
             "the newest ones, or start/end message positions; add tree for another session's page. Tool calls and results over " +
             "2,000 characters or 40 lines come shortened to their first and last lines; add full: true to read them whole. " +
-            "Results show when the messages were written (per transcript block).",
+            "Results show when the messages were written: each message header its own time, where recorded.",
         inputSchema: {
             type: "object",
             properties: {
@@ -185,7 +248,8 @@ export const MEMTREE_TOOLS = [
     },
     {
         name: "list",
-        description: "List the user's own MemTree sessions (this one and others), most recently active first: title (the tree's root summary), " +
+        description: "List the user's own MemTree sessions, most recently active first: every ccc session on any machine using this " +
+            "account (this one marked; Codex and plain claude sessions are not included). Each: title (the tree's root summary), " +
             "first message, how it ended (last user message, the tools after it and the last reply, with the time), times, " +
             "project (directory, git repo, branch, commit), models, request count and the latest tree's reference. " +
             "Filter by time, project or words in the title. Free. Open a session's tree with read_node {\"tree\": <ref>, \"id\": 0} or search {\"tree\": <ref>, ...}.",
@@ -201,18 +265,61 @@ export const MEMTREE_TOOLS = [
             },
         },
     },
+    {
+        name: "user_messages",
+        description: "The person's own messages in a session over a time range: what they typed, commands they ran, words sent while " +
+            "the agent worked, and board messages. Tool results, reminders, prompts the agent scheduled and other agents' " +
+            "messages are left out. Use it to learn what the user asked for, decided and corrected. Covers the tree and its " +
+            "newest messages no tree covers yet. Returns the newest page, oldest first; cursor lists older ones. Each " +
+            "message says where read_lines shows its context. Results show when each message was written.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tree: { type: "string", description: `${TREE_DESC} A session id works too. Omit for this session.` },
+                since: { type: "string", description: "Only messages at or after this ISO 8601 time or date (UTC unless an offset is given)." },
+                until: { type: "string", description: "Only messages before this ISO 8601 time or date." },
+                query: { type: "string", description: "Only messages holding every one of these words." },
+                cursor: { type: "string", description: "next cursor from a previous call: older messages (same other arguments)." },
+                limit: { type: "number", description: `Messages per page (default 50, at most ${USER_MESSAGES_MAX_LIMIT}).` },
+                full: { type: "boolean", description: "Long messages and pastes whole (default: shortened)." },
+                context: { type: "boolean", description: "Also the agent's last words before each message (what it answered)." },
+            },
+        },
+    },
+    {
+        name: "handover",
+        description: "A handover pack for taking over or continuing a session's work: the person's messages over its last days (each " +
+            "with the agent's words it answered), how the session ended, and a model's reading of their goals, standing " +
+            "instructions, decisions with reasons and open questions, each citing its messages. Call it first when you take " +
+            "over another session (tree: its session id or tree). The model's lists can be wrong: check one against the " +
+            "messages it cites before acting on it. A first call for a session can take up to a minute.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tree: { type: "string", description: `${TREE_DESC} A session id works too. Omit for this session.` },
+                days: { type: "number", description: `Days before the session's newest message to cover (default ${HANDOVER_DEFAULT_DAYS}, at most ${HANDOVER_MAX_DAYS}).` },
+                since: { type: "string", description: "Instead of days: messages at or after this ISO 8601 time or date." },
+                until: { type: "string", description: "Only messages before this ISO 8601 time or date." },
+            },
+        },
+    },
 ].map((tool) => ({ ...tool, _meta: MEMTREE_TOOL_META }));
 /** A request id in either spelling (UUID or the short leading-hex form). */
 const TREE_ID_RE = /^[A-Za-z0-9-]{1,64}$/;
+/** Pages of `list` results a session-id-as-tree lookup reads at most. */
+const SESSION_TREE_MAX_PAGES = 3;
+/** How long a session-id-as-tree answer is reused (its newest tree can change). */
+const SESSION_TREE_TTL_MS = 60_000;
+const SESSION_TREES_CACHED = 64;
 /** Other sessions' pages kept in memory at once (each can be several MB). */
 const OTHER_TREES_CACHED = 4;
 /** GET JSON from the loopback proxy; never throws. */
-async function proxyGetJson(fetchImpl, url, headers = {}) {
+async function proxyGetJson(fetchImpl, url, headers = {}, timeoutMs = FETCH_TIMEOUT_MS) {
     let response;
     try {
         response = await fetchImpl(url, {
             headers: { accept: "application/json", ...headers },
-            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            signal: AbortSignal.timeout(timeoutMs),
         });
     }
     catch (err) {
@@ -238,6 +345,41 @@ async function proxyGetJson(fetchImpl, url, headers = {}) {
         return { ok: false, status: response.status, error: "response was not JSON" };
     }
 }
+/**
+ * Sent with each tool's proxy reads: which tool (`page` is a whole tree's `.json`) and
+ * the calling session, which the proxy passes on so the server's one content-free log
+ * line per call can say which tool read what (polychat memtree_tool_log.py). Not to be
+ * confused with `x-memtree-tools`, the list of configured tools sent on compress calls.
+ */
+export const MEMTREE_TOOL_HEADER = "x-memtree-tool";
+export function toolHeaders(tool, deps) {
+    const headers = { [MEMTREE_TOOL_HEADER]: tool };
+    if (deps.sessionId)
+        headers["x-claude-code-session-id"] = deps.sessionId;
+    return headers;
+}
+/** How long a tool call waits to learn its process's session before using its own id. */
+const HOST_SESSION_TIMEOUT_MS = 2_000;
+/**
+ * Point `deps.sessionId` at the session this server's Claude Code process is on now.
+ * Claude Code starts the server with the session id it had at launch and does not
+ * restart it when the process moves to another session (a resume through the picker,
+ * /resume, /clear), so that id can name a session with no page ("no MemTree yet",
+ * 2026-11-09). The proxy of the ccc that launched this Claude Code knows the process's
+ * session from its SessionStart hook and answers only that process (`hostPid`: this
+ * server's parent, with the token from ccc's MCP config). Without a token (an older
+ * ccc's config: its proxy has no such route) nothing is asked; any other answer
+ * (another process, no session start seen) leaves the id as it is.
+ */
+export async function refreshHostSession(deps, hostPid = process.ppid) {
+    const base = deps.proxyUrl?.replace(/\/$/, "");
+    if (!base || !deps.hostToken)
+        return;
+    const answer = await proxyGetJson(deps.fetch ?? fetch, `${base}/memtree/host-session?host_pid=${hostPid}`, { [HOST_TOKEN_HEADER]: deps.hostToken }, HOST_SESSION_TIMEOUT_MS);
+    const sessionId = answer.ok ? answer.body?.session_id : undefined;
+    if (typeof sessionId === "string" && sessionId)
+        deps.sessionId = sessionId;
+}
 function proxyBase(deps) {
     const base = deps.proxyUrl?.replace(/\/$/, "");
     if (!base) {
@@ -260,6 +402,8 @@ function checkTreeId(tree) {
 export class CurrentTree {
     deps;
     cached;
+    /** The session `cached` was read for: a page is never reused across sessions. */
+    cachedSession;
     /** Temporary prefix pages: when each may be fetched again. */
     prefixRetryAt = new Map();
     /** The last fetched temporary prefix per page, served during its cooldown. */
@@ -267,6 +411,8 @@ export class CurrentTree {
     inFlight;
     /** Other trees, least recently used first. */
     others = new Map();
+    /** Pages whose per-message times were incomplete: when to refetch them (timesDue). */
+    timesRetryAt = new WeakMap();
     /** Set once the server answered 404 to a tree search the page JSON could answer. */
     serverSearchMissing = false;
     fetchImpl;
@@ -307,14 +453,14 @@ export class CurrentTree {
             if (limit !== undefined && Number.isFinite(limit))
                 params.set("limit", String(limit));
             const base = proxyBase(this.deps);
-            const answer = await proxyGetJson(this.fetchImpl, `${base}/memtree/${encodeURIComponent(id)}/search?${params}`);
+            const answer = await proxyGetJson(this.fetchImpl, `${base}/memtree/${encodeURIComponent(id)}/search?${params}`, toolHeaders("search", this.deps));
             const parsed = answer.ok ? serverSearchHits(answer.body) : undefined;
             if (parsed) {
                 const session = answer.body.session_id;
                 if (!other && session !== undefined)
                     this.checkSession(session, this.requireSessionId());
                 if (other || session !== undefined) {
-                    return formatSearchHits(parsed.hits, query, parsed.terms, other, serverTailHits(answer.body));
+                    return formatSearchHits(parsed.hits, query, parsed.terms, other, serverTailHits(answer.body), parsed.treeTimes);
                 }
                 // Older servers omit identity: search only the session-validated page.
             }
@@ -344,7 +490,7 @@ export class CurrentTree {
             params.set("full", "true");
         const query = params.toString() ? `?${params}` : "";
         const base = proxyBase(this.deps);
-        const answer = await proxyGetJson(this.fetchImpl, `${base}/memtree/${encodeURIComponent(id)}/messages${query}`);
+        const answer = await proxyGetJson(this.fetchImpl, `${base}/memtree/${encodeURIComponent(id)}/messages${query}`, toolHeaders("read_lines", this.deps));
         if (answer.status === 404) {
             return "No un-indexed messages after this tree: everything the server has recorded is in the tree (or the server predates tails).";
         }
@@ -357,20 +503,70 @@ export class CurrentTree {
             this.checkSession(answer.body.session_id, this.requireSessionId());
         return formatTail(answer.body, other);
     }
+    /**
+     * `/memtree/<id>/<route>`, never cached (the newest messages grow). This session's
+     * tree must be this session's (as tail); a 404 without the server's own detail means
+     * the server or this ccc's proxy predates the route.
+     */
+    async serverRead(route, tree, params) {
+        const other = checkTreeId(tree);
+        const id = other ?? (await this.currentId());
+        const query = params.toString() ? `?${params}` : "";
+        const answer = await proxyGetJson(this.fetchImpl, `${proxyBase(this.deps)}/memtree/${encodeURIComponent(id)}/${route}${query}`, toolHeaders(route, this.deps), route === "handover" ? HANDOVER_TIMEOUT_MS : FETCH_TIMEOUT_MS);
+        if (answer.status === 202)
+            throw new ToolInputError("That MemTree is still being built; try again in a minute.");
+        if (answer.status === 0 && route === "handover" && /timeout|abort/i.test(answer.error ?? "")) {
+            throw new ToolInputError("handover: the pack is still being prepared on the server; call handover again in a minute.");
+        }
+        if (answer.status === 404 && /^HTTP 404 Not Found$/.test(answer.error ?? "")) {
+            throw new ToolInputError(`${route}: this MemTree server (or this ccc) does not have it yet; update ccc or try later.`);
+        }
+        if (!answer.ok)
+            throw new ToolInputError(`${route}: ${(answer.error ?? "").replace(/^HTTP (400|404) /, "")}`);
+        if (!other)
+            this.checkSession(answer.body.session_id, this.requireSessionId());
+        return answer.body;
+    }
     async loadCurrent() {
         const id = await this.currentId();
         const sessionId = this.requireSessionId();
-        if (this.cached?.id === id)
+        if (this.cached?.id === id && !this.timesDue(this.cached.index))
             return this.cached.index;
-        const index = await this.loadPage(id, "this session", sessionId);
+        const stale = this.cached?.id === id ? this.cached.index : undefined;
+        const index = await this.refreshed(stale, () => this.loadPage(id, "this session", sessionId));
         if (!isTemporaryPrefix(index, id))
             this.cached = { id, index };
         return index;
     }
+    /**
+     * Whether a cached page's per-message times were incomplete (`line_times_incomplete`:
+     * the server's times lookup was slow) and are due a refetch. The page itself is
+     * readable meanwhile, so it stays cached; only its times are retried.
+     */
+    timesDue(index) {
+        const at = this.timesRetryAt.get(index);
+        return at !== undefined && this.now() >= at;
+    }
+    /** `load()`, or the readable `stale` copy when that fails (its times retried later). */
+    async refreshed(stale, load) {
+        if (!stale)
+            return load();
+        try {
+            return await load();
+        }
+        catch {
+            this.timesRetryAt.set(stale, this.now() + PREFIX_RETRY_INTERVAL_MS);
+            return stale;
+        }
+    }
     requireSessionId() {
         const sessionId = this.deps.sessionId;
         if (!sessionId)
             throw new ToolInputError("MemTree unavailable: the calling session id is missing");
+        if (this.cachedSession !== sessionId) {
+            this.cached = undefined; // the process moved to another session (refreshHostSession)
+            this.cachedSession = sessionId;
+        }
         return sessionId;
     }
     /** The proxy's current page for the calling session; fails closed on any other session. */
@@ -407,12 +603,13 @@ export class CurrentTree {
     }
     async getOther(id) {
         const hit = this.others.get(id);
-        if (hit) {
+        if (hit && !this.timesDue(hit)) {
             this.others.delete(id);
             this.others.set(id, hit);
             return hit;
         }
-        const index = await this.loadPage(id, `tree ${id}`);
+        const index = await this.refreshed(hit, () => this.loadPage(id, `tree ${id}`));
+        this.others.delete(id);
         if (!isTemporaryPrefix(index, id))
             this.others.set(id, index);
         while (this.others.size > OTHER_TREES_CACHED) {
@@ -445,7 +642,7 @@ export class CurrentTree {
         if (retryAt !== undefined)
             this.prefixRetryAt.set(id, now + PREFIX_RETRY_INTERVAL_MS);
         const base = proxyBase(this.deps);
-        const page = await proxyGetJson(this.fetchImpl, `${base}/memtree/${encodeURIComponent(id)}.json`);
+        const page = await proxyGetJson(this.fetchImpl, `${base}/memtree/${encodeURIComponent(id)}.json`, toolHeaders("page", this.deps));
         if (!page.ok)
             throw new ToolInputError(`MemTree unavailable (page ${id}: ${page.error})`);
         const json = page.body;
@@ -457,6 +654,9 @@ export class CurrentTree {
             throw new ToolInputError("MemTree unavailable: page belongs to a different or unknown session");
         }
         const index = new MemtreeIndex(json);
+        // Readable now; its incomplete per-message times are refetched after the cooldown.
+        if (json.line_times_incomplete === true)
+            this.timesRetryAt.set(index, this.now() + PREFIX_RETRY_INTERVAL_MS);
         if (isTemporaryPrefix(index, id)) {
             this.prefixRetryAt.set(id, this.now() + PREFIX_RETRY_INTERVAL_MS);
             this.prefixes.delete(id);
@@ -501,20 +701,83 @@ export class SessionFinder {
     }
     async listSessions(args) {
         const body = await this.get(`/memtree/sessions${sessionsQuery(args)}`, "list");
-        return formatSessions(body, args);
+        return formatSessions(body, args, this.deps.sessionId);
+    }
+    sessionTrees = new Map();
+    /** sessionTree, remembered for SESSION_TREE_TTL_MS (hits and misses: legacy ids repeat). */
+    async sessionTree(sessionId) {
+        const known = this.sessionTrees.get(sessionId);
+        if (known && this.now() - known.at < SESSION_TREE_TTL_MS)
+            return known.ref;
+        const ref = await this.lookupSessionTree(sessionId);
+        this.sessionTrees.set(sessionId, { ref, at: this.now() });
+        while (this.sessionTrees.size > SESSION_TREES_CACHED) {
+            this.sessionTrees.delete(this.sessionTrees.keys().next().value);
+        }
+        return ref;
+    }
+    async lookupSessionTree(sessionId) {
+        // `q` also matches titles and first messages, so sessions quoting the id (a hand-off)
+        // can fill the first page: follow the cursor, a few pages at most.
+        let cursor;
+        for (let page = 0; page < SESSION_TREE_MAX_PAGES; page++) {
+            const query = sessionsQuery({ q: sessionId, limit: SESSIONS_MAX_LIMIT, cursor });
+            const answer = await this.fetch(`/memtree/sessions${query}`, "list");
+            if (!answer.ok)
+                return undefined;
+            const body = answer.body;
+            if (!Array.isArray(body?.sessions))
+                return undefined;
+            const item = body.sessions.find((s) => s?.session_id === sessionId);
+            if (item) {
+                const ref = item.latest_tree?.ref ?? item.latest_tree?.request_id;
+                return typeof ref === "string" && TREE_ID_RE.test(ref) && ref !== sessionId ? ref : undefined;
+            }
+            if (typeof body.next_cursor !== "string" || !body.next_cursor || body.next_cursor === cursor) {
+                return undefined;
+            }
+            cursor = body.next_cursor;
+        }
+        return undefined;
     }
     async searchSessions(args, tree) {
-        const body = await this.get(`/memtree/search${searchQuery(args, tree)}`, "search");
+        const first = await this.fetch(`/memtree/search${searchQuery(args, tree)}`, "search");
+        let answer = first;
+        let narrowed;
+        const tried = [];
+        for (const days of RECENT_SEARCH_WINDOWS_DAYS) {
+            const recent = recentSearchArgs(args, tree, answer.status, this.now(), days);
+            if (!recent)
+                break;
+            narrowed = { args: recent, days };
+            tried.push(days);
+            answer = await this.fetch(`/memtree/search${searchQuery(recent, tree)}`, "search");
+        }
+        // No window answered: the first refusal says how to narrow the search, plus what ccc
+        // tried and, when the last try failed otherwise, how.
+        const body = this.bodyOf(answer.ok ? answer : narrowed
+            ? { ...first, error: `${first.error}${recentSearchFailedNote(tried, answer)}` } : first, "search");
         if (tree && (!body || typeof body !== "object" || body.tree !== tree)) {
             throw new ToolInputError("search: server did not confirm the requested tree; update the MemTree server before scoped search");
         }
-        return formatSearchResults(body, { ...args, tree });
+        const text = formatSearchResults(body, {
+            ...(narrowed?.args ?? args), tree,
+        });
+        if (!narrowed)
+            return text;
+        const pages = typeof body?.next_cursor === "string";
+        return `${recentSearchNote(narrowed.args.since, narrowed.days, pages)}\n\n${text}`;
+    }
+    now() {
+        return this.deps.now?.() ?? Date.now();
     }
     async get(pathAndQuery, tool) {
-        const headers = {};
-        if (this.deps.sessionId)
-            headers["x-claude-code-session-id"] = this.deps.sessionId;
-        const answer = await proxyGetJson(this.fetchImpl, `${proxyBase(this.deps)}${pathAndQuery}`, headers);
+        return this.bodyOf(await this.fetch(pathAndQuery, tool), tool);
+    }
+    fetch(pathAndQuery, tool) {
+        return proxyGetJson(this.fetchImpl, `${proxyBase(this.deps)}${pathAndQuery}`, toolHeaders(tool, this.deps));
+    }
+    bodyOf(answer, tool) {
         if (answer.ok)
             return answer.body;
         if (answer.status === 404) {
@@ -529,7 +792,9 @@ export class SessionFinder {
  */
 export async function handleMcpMessage(input, tree, finder, 
 /** versionMismatchNote: appended to failed tool calls. */
-versionNote) {
+versionNote, 
+/** A note to append once, to whichever tool answer comes first (StaleToolsNotice). */
+notice) {
     if (!isRpcRequest(input)) {
         return { jsonrpc: "2.0", id: null, error: { code: -32600, message: "Invalid Request" } };
     }
@@ -558,16 +823,20 @@ versionNote) {
         case "tools/call": {
             const name = message.params?.name;
             const args = (message.params?.arguments ?? {});
+            const withNotice = (text) => {
+                const note = notice?.next();
+                return note ? `${text}\n\n${note}` : text;
+            };
             try {
                 const text = await callTool(String(name), args, tree, finder);
-                return reply({ content: [{ type: "text", text }] });
+                return reply({ content: [{ type: "text", text: withNotice(text) }] });
             }
             catch (err) {
                 if (err instanceof UnknownToolError)
                     return fail(-32602, err.message);
                 const message = err instanceof Error ? err.message : String(err);
                 const text = versionNote ? `${message}\n${versionNote}` : message;
-                return reply({ content: [{ type: "text", text }], isError: true });
+                return reply({ content: [{ type: "text", text: withNotice(text) }], isError: true });
             }
         }
         default:
@@ -589,6 +858,35 @@ function isRpcRequest(value) {
 class UnknownToolError extends Error {
 }
 async function callTool(name, args, tree, finder) {
+    const session = await sessionAsTree(args.tree, finder);
+    if (session) {
+        const text = await dispatchTool(name, { ...args, tree: session.ref }, tree, finder);
+        return `(${session.id} is a session id: this reads its newest tree, ${session.ref}.)\n\n${text}`;
+    }
+    return dispatchTool(name, args, tree, finder);
+}
+/** A bare UUID: a session id, or a legacy request id (a ref ends in -v<N>-own/served). */
+const BARE_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * A `tree` that is a session id, resolved to that session's newest tree. Hand-offs name
+ * session ids (the instructions ask them to), and receiving agents pass them as `tree`:
+ * the page lookup then fails with 404, or a tail reads nothing (xsession benchmark,
+ * 2026-11-06). Undefined for anything else, including a legacy request id.
+ */
+async function sessionAsTree(value, finder) {
+    if (typeof value !== "string" || !BARE_UUID_RE.test(value.trim()) || !finder?.sessionTree) {
+        return undefined;
+    }
+    const id = value.trim();
+    try {
+        const ref = await finder.sessionTree(id);
+        return ref ? { id, ref } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function dispatchTool(name, args, tree, finder) {
     switch (name) {
         case "search":
             return searchTool(args, tree, finder);
@@ -602,6 +900,9 @@ async function callTool(name, args, tree, finder) {
             if (!finder)
                 throw new ToolInputError("list is not available here");
             return finder.listSessions(args);
+        case "user_messages":
+        case "handover":
+            return treeRouteTool(name, args, tree);
         default:
             throw new UnknownToolError(`Unknown tool: ${name}`);
     }
@@ -642,6 +943,16 @@ function nodeTarget(args, field) {
 function treeArgument(tree) {
     return tree === CURRENT_TREE ? undefined : checkTreeId(tree);
 }
+/** `user_messages` / `handover`: the server's answer for the tree, formatted. */
+async function treeRouteTool(name, args, tree) {
+    if (!tree.serverRead)
+        throw new ToolInputError(`${name} is not available here`);
+    const target = treeArgument(args.tree);
+    if (name === "user_messages") {
+        return formatUserMessages(await tree.serverRead(name, target, userMessagesQuery(args)), args, target);
+    }
+    return formatHandover(await tree.serverRead(name, target, handoverQuery(args)), target);
+}
 /** read_lines by leaf address (its range unless block/start/end are given), by range, or the tail. */
 async function readLinesTool(args, tree) {
     if (args.tail === true) {
@@ -679,10 +990,12 @@ export function runMemtreeMcpServer(env = process.env) {
     const deps = {
         proxyUrl: env.CCC_MEMTREE_PROXY || env.ANTHROPIC_BASE_URL,
         sessionId: env.CLAUDE_CODE_SESSION_ID || undefined,
+        hostToken: env[HOST_TOKEN_ENV] || undefined,
     };
     const tree = new CurrentTree(deps);
     const finder = new SessionFinder(deps);
     const versionNote = versionMismatchNote(env[PROXY_VERSION_ENV]);
+    const notice = new StaleToolsNotice();
     if (versionNote)
         process.stderr.write(`memtree MCP: ${versionNote}\n`);
     let buffer = "";
@@ -707,7 +1020,10 @@ export function runMemtreeMcpServer(env = process.env) {
                 continue;
             }
             queue = queue.then(async () => {
-                const response = await handleMcpMessage(message, tree, finder, versionNote).catch((err) => ({
+                // Calls run one at a time, so each reads the session its process is on now.
+                if (isToolCall(message))
+                    await refreshHostSession(deps);
+                const response = await handleMcpMessage(message, tree, finder, versionNote, notice).catch((err) => ({
                     jsonrpc: "2.0",
                     id: isRpcRequest(message) ? message.id ?? null : null,
                     error: { code: -32603, message: String(err) },
@@ -721,6 +1037,9 @@ export function runMemtreeMcpServer(env = process.env) {
         void queue.then(() => process.exit(0));
     });
 }
+function isToolCall(message) {
+    return isRpcRequest(message) && message.method === "tools/call";
+}
 function isMainModule() {
     try {
         const self = fs.realpathSync(fileURLToPath(import.meta.url));