paseo-smart-session 3.4.0 → 3.6.0

package/server/hooklib/context.mjs

@@ -0,0 +1,284 @@
+/**
+ * What every hook needs to know about the session it is running in.
+ *
+ * Two hooks now answer "how full is this context" — `context-threshold.mjs` on
+ * `PostToolUse` and `ask-compact.mjs` on `Stop` — and they must not disagree. One
+ * reading them differently from the other would mean the agent hears the number and
+ * the advice from two different sessions.
+ *
+ * Everything here reads the tail of a file rather than the whole of it: these run
+ * on the hot path, and the newest row is the only one that matters.
+ */
+
+import { closeSync, fstatSync, openSync, readdirSync, readFileSync, readSync } from "node:fs";
+import { join } from "node:path";
+
+import { pluginDir } from "./pointer.mjs";
+
+/** Enough tail to contain the last assistant message in any realistic transcript. */
+const TAIL_BYTES = 256 * 1024;
+
+/**
+ * Defaults mirroring thresholds.shared.ts, used when the plugin has not written a
+ * settings file yet. Kept in sync by a test that runs the hooks and checks where
+ * they fire against the shared module's numbers.
+ *
+ * Two profiles because a percentage of the window is the wrong unit on its own:
+ * what tires a context is the absolute prefix re-read every turn, so 30% of a
+ * million tokens is a heavier context than 85% of two hundred thousand.
+ */
+export const DEFAULT_THRESHOLDS = {
+  largeWindowFrom: 400_000,
+  large: { notice: 15, closing: 22, compact: 30, now: 40 },
+  small: { notice: 60, closing: 75, compact: 85, now: 90 },
+};
+
+export const BANDS = ["notice", "closing", "compact"];
+
+export const DEFAULT_SETTINGS = {
+  enabled: true,
+  showPill: true,
+  autoEnrol: true,
+  freshStateMinutes: 30,
+  thresholds: DEFAULT_THRESHOLDS,
+};
+
+/** The plugin's settings are the single source of truth when they exist. */
+export function readSettings() {
+  try {
+    const raw = JSON.parse(readFileSync(join(pluginDir(), "settings.json"), "utf8"));
+    const merged = { ...DEFAULT_THRESHOLDS, ...(raw.thresholds ?? {}) };
+    return {
+      // Absent means an install that predates the switch, which was always meant
+      // to be on once it could only ask rather than act.
+      enabled: raw.enabled !== false,
+      showPill: raw.showPill !== false,
+      autoEnrol: raw.autoEnrol !== false,
+      freshStateMinutes:
+        typeof raw.freshStateMinutes === "number" && raw.freshStateMinutes > 0
+          ? raw.freshStateMinutes
+          : DEFAULT_SETTINGS.freshStateMinutes,
+      thresholds: {
+        largeWindowFrom: merged.largeWindowFrom ?? DEFAULT_THRESHOLDS.largeWindowFrom,
+        large: withUpperLine(merged.large, DEFAULT_THRESHOLDS.large),
+        small: withUpperLine(merged.small, DEFAULT_THRESHOLDS.small),
+      },
+    };
+  } catch {
+    return DEFAULT_SETTINGS;
+  }
+}
+
+/**
+ * A saved profile, with the upper line filled in when it predates one.
+ *
+ * Mirrors `normalizeProfile` in thresholds.ts: the saved lower line is kept, and an
+ * absent upper line keeps the default's distance above it, never falling below it.
+ */
+export function withUpperLine(saved, fallback) {
+  const profile = { ...fallback, ...(saved ?? {}) };
+  const compact = profile.compact;
+  const migrated = Math.min(99, Math.max(fallback.now, compact + (fallback.now - fallback.compact)));
+  const raw = typeof saved?.now === "number" && Number.isFinite(saved.now) ? saved.now : migrated;
+  return { ...profile, now: Math.min(99, Math.max(Math.min(99, compact + 1), raw)) };
+}
+
+export function profileFor(maxTokens, thresholds) {
+  return maxTokens >= thresholds.largeWindowFrom ? thresholds.large : thresholds.small;
+}
+
+/**
+ * Whether this agent is one the governor may speak to.
+ *
+ * The same rule settings.server.ts resolves, duplicated here because a hook on the
+ * hot path must not open a daemon connection to answer it: an explicit answer in
+ * `enrolment.json` outranks the state-file inference in both directions, and the
+ * inference itself only counts while `autoEnrol` is on.
+ */
+export function isEnrolled(agentId, settings = readSettings()) {
+  if (typeof agentId !== "string" || agentId === "") return false;
+  try {
+    const overrides = JSON.parse(readFileSync(join(pluginDir(), "enrolment.json"), "utf8"));
+    if (typeof overrides?.[agentId] === "boolean") return overrides[agentId];
+  } catch {
+    // No file, or one we cannot read: nobody has overridden anything.
+  }
+  if (!settings.autoEnrol) return false;
+  try {
+    return readdirSync(join(pluginDir(), "state")).includes(`${agentId}.md`);
+  } catch {
+    return false;
+  }
+}
+
+/** The tail of a file as text, or null if it cannot be read. */
+function tail(path, bytes) {
+  let fd;
+  try {
+    fd = openSync(path, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const size = fstatSync(fd).size;
+    const length = Math.min(size, bytes);
+    const buffer = Buffer.allocUnsafe(length);
+    readSync(fd, buffer, 0, length, size - length);
+    return buffer.toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Context occupancy from the last assistant message's usage.
+ *
+ * input + cache_read + cache_creation + output is the same arithmetic Claude Code
+ * itself documents for a resumed session's `context_tokens`, so it is the
+ * sanctioned way to ask "how much of the window is currently occupied".
+ */
+export function readContextTokens(transcriptPath) {
+  const text = tail(transcriptPath, TAIL_BYTES);
+  if (text === null) return null;
+  const lines = text.split("\n");
+
+  // Backwards: the newest assistant message wins, and a partial first line from
+  // slicing mid-file simply fails to parse and is skipped.
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index];
+    if (line === undefined || line === "" || !line.includes('"usage"')) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry?.type !== "assistant") continue;
+    // A subagent's usage is its own window, not the main thread's.
+    if (entry.isSidechain === true) continue;
+    const usage = entry.message?.usage;
+    if (usage === undefined) continue;
+    const used =
+      (usage.input_tokens ?? 0) +
+      (usage.cache_read_input_tokens ?? 0) +
+      (usage.cache_creation_input_tokens ?? 0) +
+      (usage.output_tokens ?? 0);
+    return { used, model: entry.message?.model ?? null };
+  }
+  return null;
+}
+
+/**
+ * Models whose context window is not the current default of 1M.
+ *
+ * The transcript records the resolved model id (`claude-opus-5`), never the config
+ * alias (`opus[1m]`), so the suffix is not a signal. Every current Opus, Sonnet and
+ * Fable model has a 1M window; Haiku and the older generations do not.
+ */
+const SMALL_WINDOW = /haiku|-3-|sonnet-3|opus-3|sonnet-4-5|opus-4-5|sonnet-4-20|opus-4-20/;
+
+/**
+ * The window size Paseo reported for this agent, from the recorder's own log.
+ *
+ * Read from the tail, like the transcript: this is the hot path, and the newest row
+ * is the only one that matters.
+ */
+function recordedWindow() {
+  const agentId = process.env.PASEO_AGENT_ID;
+  if (agentId === undefined || agentId === "") return null;
+  const month = new Date().toISOString().slice(0, 7);
+  const text = tail(join(pluginDir(), `context-${month}.jsonl`), 64 * 1024);
+  if (text === null) return null;
+
+  const lines = text.split("\n");
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index];
+    if (line === undefined || !line.includes(agentId)) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row.agentId === agentId && typeof row.maxTokens === "number" && row.maxTokens > 0) {
+        return row.maxTokens;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * The window size for this session.
+ *
+ * Getting this wrong is worse than not warning at all: assuming 200k on a 1M
+ * session warns at a fifth of the real occupancy and reports negative headroom.
+ * So the first choice is what Paseo actually measured for this agent — recorded by
+ * the plugin, read from the tail of its log — and the model table is the fallback.
+ */
+export function windowFor(model) {
+  const override = Number(process.env.SMART_SESSION_CONTEXT_WINDOW ?? "");
+  if (Number.isFinite(override) && override > 0) return override;
+
+  const recorded = recordedWindow();
+  if (recorded !== null) return recorded;
+
+  if (typeof model === "string" && SMALL_WINDOW.test(model)) return 200_000;
+  return 1_000_000;
+}
+
+/**
+ * Occupancy, the window it is measured against, and the bands that apply.
+ *
+ * Returns null when the transcript says nothing yet — a session with no completed
+ * assistant turn has no usage to read, and guessing would be worse than silence.
+ */
+export function occupancy(transcriptPath, settings = readSettings()) {
+  const reading = readContextTokens(transcriptPath);
+  if (reading === null) return null;
+  const max = windowFor(reading.model);
+  return {
+    used: reading.used,
+    max,
+    model: reading.model,
+    pct: Math.floor((reading.used / max) * 100),
+    profile: profileFor(max, settings.thresholds),
+  };
+}
+
+/**
+ * Names Smart Session's tools in agent-facing text as this agent has them. On Paseo 0.15+ they are
+ * served through Paseo's own MCP with a `smart_` prefix (`SMART_SESSION_TOOLS=native` in the
+ * agent's environment); sessions opened before that, and the stdio fallback, keep the bare names.
+ */
+const TOOL_MENTION = /\b(call|Call|with) (checkpoint|request_compaction|defer_compaction|context_status|budget_status)\b/g;
+export function named(text, native = toolsMode() === "native") {
+  return native ? text.replace(TOOL_MENTION, "$1 smart_$2") : text;
+}
+
+/**
+ * Which tools this session has. Native tools live in the plugin process, so a plugin update or reload detaches them
+ * from every open session until it reopens (Paseo 0.15.2 reopens a session before that agent's next prompt). The
+ * worker records its instance in `tools-instance.json` and each native attach the instance that attached it in
+ * `tools/native-<agentId>.json`; a mismatch means "detached".
+ */
+export function toolsMode(env = process.env) {
+  if (env.SMART_SESSION_TOOLS !== "native") return env.SMART_SESSION_TOOLS === "stdio" ? "stdio" : "legacy";
+  const read = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; } };
+  const current = read(join(pluginDir(), "tools-instance.json"));
+  const agentId = env.PASEO_AGENT_ID;
+  const mine = agentId ? read(join(pluginDir(), "tools", `native-${agentId.replace(/[^A-Za-z0-9_-]/g, "_")}.json`)) : null;
+  return current?.instance && mine?.instance !== current.instance ? "detached" : "native";
+}
+
+/** What a detached session is told: the same tools, one call each, through mcp.mjs beside this plugin's hooks. */
+export function detachedNotice(bridge) {
+  return `Smart Session was updated while this session was open, so its smart_* tools are detached and fail with "Tool not found" until this session reopens (Paseo reopens it before your next prompt). Until then run the same tools by their plain names: node ${JSON.stringify(bridge)} call <tool> '<json>' (for example: call checkpoint '{"current_step":"..."}'). Do not mention this to the user.`;
+}
+
+/** Agent-facing text for this session's tools: smart_ names, plain names, or plain names plus the bridge. */
+export function forTools(text, bridge) {
+  const mode = toolsMode();
+  if (mode === "native") return named(text, true);
+  return mode === "detached" ? `${text}\n\n${detachedNotice(bridge)}` : text;
+}

package/server/hooklib/pointer.mjs

@@ -0,0 +1,149 @@
+/**
+ * The state-file pointer, and the two ways it can reach the model.
+ *
+ * Compaction is the one moment the agent is deciding what it knows, so it is the
+ * one moment worth spending an injection on. But `PostCompact` — the event that
+ * knows a compaction happened — cannot inject: Claude Code validates
+ * `hookSpecificOutput.hookEventName` against a union that does not contain it, and
+ * rejects the whole output. So the pointer is written here as a small pending note
+ * and delivered by whichever hook speaks first:
+ *
+ *   - `SessionStart` with `source: "compact"`, which fires in the emptied context
+ *     and does accept `additionalContext`; or
+ *   - the next `PostToolUse`, which is guaranteed to run.
+ *
+ * Whoever delivers it clears it, so it is said exactly once.
+ *
+ * Keyed by Paseo agent id when there is one, because that survives compaction
+ * whatever Claude Code decides to do with the session id.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function pluginDir() {
+  const home = process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+  return join(home, "plugin-data", "smart-session");
+}
+
+/** The same derivation the agent's `checkpoint` tool uses. */
+export function statePath() {
+  const override = process.env.SMART_SESSION_STATE_FILE;
+  if (override !== undefined && override !== "") return override;
+  const agentId = process.env.PASEO_AGENT_ID;
+  if (agentId === undefined || agentId === "") return null;
+  return join(pluginDir(), "state", `${agentId}.md`);
+}
+
+/** Seconds since the state file was last written, or null if there isn't one. */
+export function stateAgeSeconds(path) {
+  if (path === null || !existsSync(path)) return null;
+  try {
+    return Math.round((Date.now() - statSync(path).mtimeMs) / 1000);
+  } catch {
+    return null;
+  }
+}
+
+const STALE_AFTER_SECONDS = 30 * 60;
+
+/**
+ * What the continuation needs to hear, given what is actually on disk.
+ *
+ * Returns null when there is nowhere to point — no agent id, no override — since
+ * naming no file at all would be worse than silence.
+ */
+export function pointerText(path = statePath(), age = stateAgeSeconds(path)) {
+  if (path === null) return null;
+  if (age === null) {
+    return (
+      `No durable state file exists yet for this session (expected at ${path}). Everything not in the summary above is now gone. ` +
+      "Before continuing, write down the goal, the step in progress and its exact next action, decisions made and why, and every approach already tried and rejected — then keep it current, so the next compaction costs nothing."
+    );
+  }
+  const lines = [
+    `Durable task state for this session is at ${path}. Re-read it before acting. Where it disagrees with the summary above, the file is correct — it was written deliberately; the summary was compressed automatically.`,
+  ];
+  // A state file older than the work it is supposed to describe is worse than
+  // none, because it reads as authoritative. Say so plainly.
+  if (age > STALE_AFTER_SECONDS) {
+    lines.push(
+      `Note: that file was last written ${Math.round(age / 60)} minutes ago, so it may predate recent work. Reconcile it against the summary and update it before continuing.`,
+    );
+  }
+  return lines.join(" ");
+}
+
+function pointerPath(sessionId) {
+  const agentId = process.env.PASEO_AGENT_ID;
+  const key = agentId !== undefined && agentId !== "" ? agentId : sessionId;
+  if (typeof key !== "string" || key === "") return null;
+  return join(pluginDir(), "pointers", `${key.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+}
+
+function readNote(sessionId) {
+  const path = pointerPath(sessionId);
+  if (path === null) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeNote(sessionId, note) {
+  const path = pointerPath(sessionId);
+  if (path === null) return;
+  try {
+    mkdirSync(join(pluginDir(), "pointers"), { recursive: true });
+    writeFileSync(path, JSON.stringify(note), "utf8");
+  } catch {
+    // A hook that cannot persist its note must still not break the turn.
+  }
+}
+
+/** Leaves the pointer where either delivery path will find it. */
+export function writePending(sessionId, text) {
+  if (text === null) return;
+  writeNote(sessionId, { at: new Date().toISOString(), text });
+}
+
+/**
+ * Records that the pointer has already reached the model for this compaction.
+ *
+ * Measured on a real compaction: `SessionStart:compact` fires ~55ms *before*
+ * `PostCompact`, so without this the later event would queue a note that the next
+ * tool call repeats. The marker is left in place rather than deleted — the next
+ * compaction overwrites it, and an absent file has to keep meaning "nothing
+ * pending".
+ */
+export function markDelivered(sessionId) {
+  writeNote(sessionId, { at: new Date().toISOString(), delivered: true });
+}
+
+/** Whether this compaction's pointer was already said, within `withinMs`. */
+export function deliveredRecently(sessionId, withinMs) {
+  const note = readNote(sessionId);
+  if (note?.delivered !== true) return false;
+  const at = Date.parse(note.at ?? "");
+  return Number.isFinite(at) && Date.now() - at < withinMs;
+}
+
+/** The pending pointer, without consuming it — nothing is cleared until it is said. */
+export function readPending(sessionId) {
+  const note = readNote(sessionId);
+  if (note === null || note.delivered === true) return null;
+  return typeof note.text === "string" && note.text !== "" ? note.text : null;
+}
+
+/** Called only once the pointer has actually been written to stdout. */
+export function clearPending(sessionId) {
+  const path = pointerPath(sessionId);
+  if (path === null) return;
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // A stale note costs one repeated sentence, never a failed turn.
+  }
+}

package/server/install-on-load.ts

@@ -13,7 +13,8 @@
  * machine's real Claude Code settings just because something imported a function.
  */
 
-import { install } from "./install.ts";
+import { install, resolvePluginDir } from "./install.ts";
+import { removeGlobalRegistrations } from "./mcp-registrations.ts";
 
 void install()
   .then((report) => {
@@ -33,3 +34,16 @@ void install()
     }
   })
   .catch((error: unknown) => console.error("[smart-session] hook install failed", String(error)));
+
+// Older versions registered the agent tools globally; they are attached per launch now. Only an
+// install Paseo actually loads from this PASEO_HOME does this, so a check that loads the bundle
+// against a sandbox (check-teardown.mjs) never reaches the machine's real Claude and Codex homes.
+void resolvePluginDir()
+  .then((directory) => (directory === null ? [] : removeGlobalRegistrations()))
+  .then((results) => {
+    for (const result of results) {
+      if (result.status === "removed") console.log(`[smart-session] removed the global MCP registration from ${result.path} (backup beside it)`);
+      if (result.status === "error" || result.status === "unavailable") console.error(`[smart-session] could not remove the global MCP registration from ${result.path}: ${result.error ?? "no claude CLI on PATH"}`);
+    }
+  })
+  .catch(() => undefined);

package/server/mcp-registrations.ts

@@ -0,0 +1,126 @@
+import { execFile } from "node:child_process";
+import { chmod, copyFile, readFile, readdir, realpath, rename, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { promisify } from "node:util";
+
+/**
+ * Smart Session's agent tools are attached per launch (natively on Paseo 0.15+, or as a per-launch
+ * stdio server), so a user-scope "smart-session" MCP entry left by an older version only makes every
+ * Claude or Codex session on the machine, Paseo's or not, start its own `node mcp.mjs` — or fail to,
+ * when it points at an install directory a later update removed. This removes such entries from
+ * every Claude and Codex home Paseo launches agents with, backing each file up first.
+ *
+ * An entry is ours only when it runs this plugin's `mcp.mjs`. `.claude.json` holds credentials, so
+ * it is read but never written here: `claude mcp remove` does that, under Claude Code's own lock,
+ * with `CLAUDE_CONFIG_DIR` pointing at the home in question.
+ */
+export type Unregistered = { path: string; status: "removed" | "absent" | "foreign" | "unavailable" | "error"; error?: string };
+const NAME = "smart-session";
+const BACKUP = ".smart-session-unregister.bak";
+const OURS = /(?:^|[\\/])(?:paseo-smart-session|smart-session)[\\/](?:.*[\\/])?mcp\.mjs$/;
+const execFileAsync = promisify(execFile);
+
+/** Every Claude global config (.claude.json) and Codex config.toml Paseo may launch an agent with. */
+export async function agentHomes(env: NodeJS.ProcessEnv = process.env, paseoHome = env.PASEO_HOME ?? join(homedir(), ".paseo"), home = homedir()): Promise<{ claude: string[]; codex: string[] }> {
+  const claudeDirs = new Set<string>([env.CLAUDE_CONFIG_DIR?.trim() || home, home]);
+  const codexDirs = new Set<string>([env.CODEX_HOME?.trim() || join(home, ".codex"), join(home, ".codex")]);
+  // Homes set in Paseo's provider settings (agents.providers.<id>.env).
+  try {
+    const config = JSON.parse(await readFile(join(paseoHome, "config.json"), "utf8"));
+    for (const provider of Object.values(config?.agents?.providers ?? {}) as { env?: Record<string, string> }[]) {
+      if (provider?.env?.CLAUDE_CONFIG_DIR) claudeDirs.add(provider.env.CLAUDE_CONFIG_DIR);
+      if (provider?.env?.CODEX_HOME) codexDirs.add(provider.env.CODEX_HOME);
+    }
+  } catch { /* No config: the defaults. */ }
+  // Homes ZeroSub creates per account (~/.paseo/zerosub/homes/<id>/), Claude and Codex alike. ZeroSub
+  // seeds them from the main .claude.json, which is in the list above, so the entry does not come back.
+  const zerosub = join(paseoHome, "zerosub", "homes");
+  for (const entry of await readdir(zerosub, { withFileTypes: true }).catch(() => [])) {
+    if (!entry.isDirectory()) continue;
+    claudeDirs.add(join(zerosub, entry.name)); codexDirs.add(join(zerosub, entry.name));
+  }
+  const existing = async (paths: string[]) => [...new Set((await Promise.all(paths.map(async (p) => (await stat(p).catch(() => null))?.isFile() ? await realpath(p) : null))).filter((p): p is string => !!p))];
+  return {
+    claude: await existing([...claudeDirs].map((dir) => join(resolve(dir), ".claude.json"))),
+    codex: await existing([...codexDirs].map((dir) => join(resolve(dir), "config.toml"))),
+  };
+}
+
+const ours = (server: unknown) => {
+  const entry = server as { command?: unknown; args?: unknown } | null;
+  return [entry?.command, ...(Array.isArray(entry?.args) ? entry.args : [])].some((part) => typeof part === "string" && OURS.test(part));
+};
+
+async function backup(path: string): Promise<void> {
+  await copyFile(path, path + BACKUP, 1).catch((error) => { if (error.code !== "EEXIST") throw error; });
+  await chmod(path + BACKUP, (await stat(path)).mode & 0o777);
+}
+
+export type RunClaude = (args: string[], env: NodeJS.ProcessEnv) => Promise<unknown>;
+const runClaude: RunClaude = (args, env) => execFileAsync("claude", args, { env, timeout: 30_000, maxBuffer: 1024 * 1024 });
+
+export async function unregisterClaude(path: string, run: RunClaude = runClaude, home = homedir()): Promise<Unregistered> {
+  try {
+    const entry = JSON.parse(await readFile(path, "utf8"))?.mcpServers?.[NAME];
+    if (!entry) return { path, status: "absent" };
+    if (!ours(entry)) return { path, status: "foreign" };
+    await backup(path);
+    const env: NodeJS.ProcessEnv = { ...process.env };
+    // ~/.claude.json is the default home's; any other directory is a CLAUDE_CONFIG_DIR.
+    if (dirname(path) === await realpath(home).catch(() => resolve(home))) delete env.CLAUDE_CONFIG_DIR; else env.CLAUDE_CONFIG_DIR = dirname(path);
+    try { await run(["mcp", "remove", NAME, "--scope", "user"], env); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return { path, status: "unavailable" };
+      throw error;
+    }
+    const after = JSON.parse(await readFile(path, "utf8"))?.mcpServers?.[NAME];
+    return after ? { path, status: "error", error: "still registered after claude mcp remove" } : { path, status: "removed" };
+  } catch (error) { return { path, status: "error", error: (error as Error).message }; }
+}
+
+/** Removes [mcp_servers.smart-session] and its sub-tables when they run our mcp.mjs, keeping everything else verbatim. */
+export function withoutCodexEntry(text: string): string | null {
+  const lines = text.split("\n");
+  const header = (line: string) => /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/.exec(line)?.[1].replace(/["']/g, "") ?? null;
+  const mine = (name: string | null) => name === `mcp_servers.${NAME}` || name?.startsWith(`mcp_servers.${NAME}.`);
+  const tables: { start: number; end: number }[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!mine(header(lines[i]!))) continue;
+    let end = i + 1;
+    while (end < lines.length && header(lines[end]!) === null) end++;
+    // Comments and blank lines just above the next table belong to it.
+    while (end > i + 1 && /^\s*(#.*)?$/.test(lines[end - 1]!)) end--;
+    tables.push({ start: i, end }); i = end - 1;
+  }
+  if (!tables.length) return null;
+  const body = tables.map((t) => lines.slice(t.start, t.end).join("\n")).join("\n");
+  const strings = [...body.matchAll(/["']([^"']+)["']/g)].map((m) => m[1]!);
+  if (!strings.some((value) => OURS.test(value))) return text;
+  const keep = lines.filter((_, i) => !tables.some((t) => i >= t.start && i < t.end));
+  return keep.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
+export async function unregisterCodex(path: string): Promise<Unregistered> {
+  try {
+    const text = await readFile(path, "utf8");
+    const next = withoutCodexEntry(text);
+    if (next === null) return { path, status: "absent" };
+    if (next === text) return { path, status: "foreign" };
+    await backup(path);
+    const temporary = `${path}.smart-session.${randomBytes(4).toString("hex")}.tmp`;
+    await writeFile(temporary, next, { mode: (await stat(path)).mode & 0o777 });
+    await rename(temporary, path);
+    return { path, status: "removed" };
+  } catch (error) { return { path, status: "error", error: (error as Error).message }; }
+}
+
+/** Removes Smart Session's own global registrations from every known home. Never throws. */
+export async function removeGlobalRegistrations(homes?: { claude: string[]; codex: string[] }, run: RunClaude = runClaude, home = homedir()): Promise<Unregistered[]> {
+  const found = homes ?? await agentHomes().catch(() => ({ claude: [], codex: [] }));
+  // One at a time: `claude mcp remove` is a whole CLI process, and they would share the main file's lock.
+  const results: Unregistered[] = [];
+  for (const path of found.claude) results.push(await unregisterClaude(path, run, home));
+  for (const path of found.codex) results.push(await unregisterCodex(path));
+  return results;
+}

package/server/native-tools.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import type { AgentToolContext, AgentToolDefinition, PluginSessionOpenRequest } from "@getpaseo/plugin/server";
+import { TOOL_SHAPES, agentTools, named } from "./agent-tools.mjs";
+
+/**
+ * Smart Session's agent tools served natively (Paseo 0.15+). At `agent.session_open` they go on
+ * `request.tools`, and the daemon lists them on the agent's own Paseo MCP server and routes each
+ * call here over IPC. No process per agent, and the caller's id comes from the daemon's per-agent
+ * endpoint rather than an environment variable. `mcp.mjs` stays as the per-launch fallback where
+ * the host doesn't serve plugin tools (`nativeToolsAvailable`).
+ *
+ * Names carry a `smart_` prefix: plugin tools share one namespace with Paseo's own, and a
+ * collision fails the agent's whole Paseo tool list.
+ */
+export const PREFIX = "smart_";
+
+type PaseoConfig = {
+  daemon?: { mcp?: { enabled?: boolean; injectIntoAgents?: boolean } };
+  agents?: { providers?: Record<string, { paseoTools?: { enabled?: boolean; disabledTools?: string[] } }> };
+};
+
+/** Whether this host serves plugin tools to this agent: `request.tools` exists, the daemon injects its MCP, and the provider's Paseo tools aren't off. */
+export function nativeToolsAvailable(request: Pick<PluginSessionOpenRequest, "provider"> & { tools?: unknown }, config: PaseoConfig | null): boolean {
+  if (!Array.isArray(request.tools)) return false;
+  if (config?.daemon?.mcp?.enabled === false || config?.daemon?.mcp?.injectIntoAgents === false) return false;
+  const policy = config?.agents?.providers?.[request.provider]?.paseoTools;
+  if (policy?.enabled === false) return false;
+  return !policy?.disabledTools?.some((name) => name.startsWith(PREFIX));
+}
+
+/** Calls one of this plugin's RPCs in-process, as the stdio server would over the daemon. */
+export type Invoke = (method: string, input: unknown, context: AgentToolContext) => Promise<unknown>;
+
+const fromJSONSchema = (schema: unknown): z.ZodType =>
+  (z as unknown as { fromJSONSchema: (schema: unknown) => z.ZodType }).fromJSONSchema(schema);
+
+/** The tool definitions for one session. The same text and rules as `mcp.mjs`, run in this process. */
+export function nativeTools(invoke: Invoke): AgentToolDefinition[] {
+  // Built once per worker: the definitions hold no per-session state (the caller comes with each call).
+  const cached = built.get(invoke);
+  if (cached) return cached;
+  const tools = TOOL_SHAPES.map((shape) => ({
+    name: PREFIX + shape.name,
+    description: named(shape.description, true),
+    input: fromJSONSchema(shape.inputSchema),
+    async execute(input: unknown, context: AgentToolContext) {
+      try {
+        const tools = agentTools({ agentId: context.agent.id, call: (method, payload) => invoke(method, payload, context) });
+        const text = await tools[shape.name as keyof typeof tools].run((input ?? {}) as Record<string, unknown>);
+        return { text: named(text, true) };
+      } catch (error) {
+        // A tool result, not a protocol error, so the model reads it, as in mcp.mjs.
+        return { isError: true, text: `Failed: ${error instanceof Error ? error.message : String(error)}` };
+      }
+    },
+  }));
+  built.set(invoke, tools);
+  return tools;
+}
+const built = new WeakMap<Invoke, AgentToolDefinition[]>();