@tiagojct/subsub 0.10.0 → 0.11.1

package/src/init.ts

@@ -4,7 +4,7 @@
  *
  * Writes:
  * - the settings file (~/.config/subsub/config.json): profile, name, language,
- *   Sub-Sub folder, library changes, model;
+ *   Sub-Sub folder, models;
  * - the server settings file (~/.config/zotero-local-mcp/env, or the one that
  *   already exists): the Sub-Sub folder, tag list, alerts file, contact email.
  *   Other lines stay;
@@ -19,7 +19,7 @@
  * Flags (for scripts and tests): --yes (take every default), --setup
  * standard|fmup, --name, --about, --language, --folder (or --notes), --move
  * yes|no, --profile, --tags health-sciences|health-informatics|any-field,
- * --library on|off, --email, --starbuck on|off, --models keep|later|opencode-go.
+ * --email, --starbuck on|off, --models keep|later|opencode-go.
  */
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -29,7 +29,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import {
 	configPath,
-	DEFAULT_MODEL,
+	DEFAULT_MODELS,
 	expand,
 	isProfile,
 	loadConfig,
@@ -53,7 +53,7 @@ export const STARTER_TAGS: Record<string, string> = {
 	"any-field": "Any field: methods and document types only; Sub-Sub proposes topics from your library",
 };
 
-export const TESTED_MODEL = DEFAULT_MODEL;
+export const TESTED_MODELS = DEFAULT_MODELS;
 
 export interface InitIO {
 	ask(question: string, def: string): Promise<string>;
@@ -152,8 +152,8 @@ export async function runInit(
 	// Without questions (--yes), an existing folder stays exactly as it is.
 	const keepAsIs = Boolean(flags.yes) && !flags.folder && !flags.notes && oldFolder !== undefined;
 	const folderDefault = flags.folder ?? flags.notes ?? (oldFolder ? (keepAsIs ? oldFolder : subsubFolder(oldFolder)) : join(home, "Documents", FOLDER_NAME));
-	const answer = expand((await io.ask("Sub-Sub folder (or an Obsidian vault)", folderDefault)).trim() || folderDefault, home);
-	const notes = keepAsIs && answer === oldFolder ? answer : subsubFolder(answer);
+	const answer = expand(cleanPath(await io.ask("Sub-Sub folder (or an Obsidian vault)", folderDefault)) || folderDefault, home);
+	let notes = keepAsIs && answer === oldFolder ? answer : subsubFolder(answer);
 	if (notes !== answer) io.say(`That is an Obsidian vault. Sub-Sub will use ${notes}.`);
 
 	// ---- files of the old layout
@@ -171,10 +171,16 @@ export async function runInit(
 			"Move them",
 			[
 				{ value: "yes", label: "Move them (recommended)" },
-				{ value: "no", label: from === notes ? "Leave them; Sub-Sub still reads them from Systems/" : "Leave them where they are" },
+				// In a new folder, files left behind would not be read: then "no" means keeping the old folder.
+				{ value: "no", label: from === notes ? "Leave them; Sub-Sub still reads them from Systems/" : flags.folder || flags.notes ? "Leave them where they are" : `Leave them, and keep using ${from}` },
 			],
 			flags.move ?? (flags.yes ? "no" : "yes"),
 		);
+		// A folder given on the command line (--folder, --notes) is a deliberate choice and stays.
+		if (move === "no" && from !== notes && !flags.folder && !flags.notes) {
+			notes = from;
+			io.say(`Sub-Sub keeps using ${notes}.`);
+		}
 	}
 
 	explain("Profile", "The profile sets how much Sub-Sub writes for you and which tools it offers. Change it at any time with /profile.");
@@ -185,19 +191,6 @@ export async function runInit(
 		isProfile(profileDefault) ? profileDefault : "scholar",
 	);
 
-	explain(
-		"Library changes",
-		"With library changes on, Sub-Sub can import, tag and repair items in Zotero. It shows a preview of every change, and nothing changes until you select Yes. With them off, it only reads, searches and writes notes. Switch at any time with /library on or /library off.",
-	);
-	const library = await io.choose(
-		"Library changes",
-		[
-			{ value: "on", label: "On (recommended): every change shows a preview first" },
-			{ value: "off", label: "Off: read, search and write notes only" },
-		],
-		flags.library ?? (existing.libraryChanges === false ? "off" : "on"),
-	);
-
 	// The tag list: a custom path in the server settings stays; otherwise Zotero/Zotero tags.md (moved, kept or new).
 	const vocabTarget = join(notes, SETTINGS_DIR, SETTINGS_FILES.tags);
 	const oldDefaults = new Set([join(from, "Systems", SETTINGS_FILES.tags), join(from, SETTINGS_DIR, SETTINGS_FILES.tags)]);
@@ -220,7 +213,7 @@ export async function runInit(
 		);
 	}
 
-	explain("Contact email", "Unpaywall needs an email address to find open-access PDFs. Sub-Sub sends it only to Unpaywall, Crossref, OpenAlex and PubMed, as they ask.");
+	explain("Contact email", "Unpaywall needs an email address to find open-access PDFs. Sub-Sub sends it with its requests to PubMed, Europe PMC, OpenAlex, Crossref and Unpaywall, as they ask, and to nobody else.");
 	const email = (await io.ask("Email (optional)", flags.email ?? envValues.ZOTERO_CONTACT_EMAIL ?? "")).trim();
 
 	explain("Reference checks (Starbuck)", "An optional add-on for manuscripts: it checks that each cited work exists, matches its citation and was not retracted. Sub-Sub then has /verify.");
@@ -233,16 +226,20 @@ export async function runInit(
 		flags.starbuck ?? (starbuckEnabled(current) ? "on" : "off"),
 	);
 
-	explain("Models", "Sub-Sub needs an account with a model provider. You can connect one later in Sub-Sub with the model button (or /login in the terminal).");
+	explain(
+		"Models",
+		"Sub-Sub needs an account with a model provider. Each mode can use its own model: the Librarian a fast, cheap one for tags and imports, the Researcher a stronger one for reading. You can connect a provider later in Sub-Sub with the model button (or /login in the terminal).",
+	);
 	const hadModel = "model" in existing || "models" in existing;
+	const show = (m: Partial<Record<string, string>>) => (Object.keys(m).length ? Object.entries(m).map(([k, v]) => `${k} ${v}`).join(", ") : "choose in Sub-Sub");
 	const modelOptions = [
-		...(hadModel ? [{ value: "keep", label: `Keep: ${current.model ?? "choose in Sub-Sub"}` }] : []),
+		...(hadModel ? [{ value: "keep", label: `Keep: ${show(current.models)}` }] : []),
 		{ value: "later", label: "Choose later in Sub-Sub" },
-		{ value: "opencode-go", label: `OpenCode Go, tested: ${TESTED_MODEL}` },
+		{ value: "opencode-go", label: `OpenCode Go, tested: ${TESTED_MODELS.librarian} for the Librarian, ${TESTED_MODELS.researcher} for the Researcher` },
 	];
 	const agentDir = initEnv.SUBSUB_AGENT_DIR ? expand(initEnv.SUBSUB_AGENT_DIR, home) : join(home, ".subsub", "agent");
 	const modelDefault = hadModel ? "keep" : hasProvider(agentDir, "opencode") ? "opencode-go" : "later";
-	const models = await io.choose("Model", modelOptions, flags.models ?? modelDefault);
+	const models = await io.choose("Models", modelOptions, flags.models ?? modelDefault);
 
 	// ---- write
 	if (move === "yes") applyMoves(moves);
@@ -278,15 +275,14 @@ export async function runInit(
 		setup: fmup ? "fmup" : undefined,
 		vault: notes,
 		envFile,
-		libraryChanges: library === "on",
-		defaultMode: undefined,
+		libraryChanges: undefined,
 		addons: withStarbuck(current.addons, starbuck === "on"),
 	};
-	// One model since 0.10: the per-mode models are replaced.
-	patch.models = undefined;
-	if (models === "keep") patch.model = current.model ?? "";
-	if (models === "later") patch.model = "";
-	if (models === "opencode-go") patch.model = TESTED_MODEL;
+	// A model per mode; "model" (0.10, one for both) is replaced.
+	patch.model = undefined;
+	if (models === "keep") patch.models = current.models;
+	if (models === "later") patch.models = {};
+	if (models === "opencode-go") patch.models = TESTED_MODELS;
 	saveConfig(patch, initEnv);
 
 	const zotero = await zoteroReachable(deps.fetch);
@@ -374,3 +370,11 @@ export async function initMain(args: string[], env: NodeJS.ProcessEnv = process.
 		(io as { close?: () => void }).close?.();
 	}
 }
+
+/** A path as typed, dragged from Finder (spaces escaped) or copied from Explorer (in quotes). */
+export function cleanPath(raw: string): string {
+	let p = raw.trim();
+	if (p.length > 1 && (p[0] === '"' || p[0] === "'") && p.at(-1) === p[0]) return p.slice(1, -1);
+	if (process.platform !== "win32") p = p.replace(/\\([ '"()&])/g, "$1");
+	return p;
+}

package/src/look.ts

@@ -83,8 +83,7 @@ export function libraryLine(st: LibraryState): { text: string; warn: boolean } {
 /** Header lines. Each line is cut to the width before it is coloured. */
 export function headerLines(opts: {
 	version: string;
-	/** Library changes on (false: read only). */
-	libraryChanges: boolean;
+	mode: "librarian" | "researcher";
 	/** Profile label, e.g. "Scholar". */
 	profile?: string;
 	model: string;
@@ -95,7 +94,7 @@ export function headerLines(opts: {
 }): string[] {
 	const p = opts.paint ?? plain;
 	const w = Math.max(10, opts.width);
-	const modeLabel = `Assistant${opts.profile ? `, ${opts.profile}` : ""}${opts.libraryChanges ? "" : ", read only"}`;
+	const modeLabel = (opts.mode === "librarian" ? "Librarian" : "Researcher") + (opts.profile ? `, ${opts.profile}` : "");
 	const lib = libraryLine(opts.library);
 	if (w < BANNER[0].length + 2) {
 		return [p.mark(cut(`Sub-Sub ${opts.version}`, w)), p.text(cut(`${modeLabel} | ${opts.model}`, w)), (lib.warn ? p.warn : p.muted)(cut(lib.text, w))];
@@ -108,7 +107,7 @@ export function headerLines(opts: {
 		if ([...one].length <= w) out.push(p.dim(one));
 		else out.push(p.dim(cut(`"${opts.quote[0]}"`, w)), p.dim(cut(`  (${opts.quote[1]})`, w)));
 	}
-	out.push(p.dim(cut("/library  /profile  /history  /undo  |  / for all commands", w)), "");
+	out.push(p.dim(cut("/researcher  /librarian  /profile  /history  /undo  |  / for all commands", w)), "");
 	return out;
 }
 

package/src/paths.ts

@@ -92,6 +92,27 @@ export type PathVerdict = { ok: true } | { ok: false; why: string };
 export function judgePath(target: string, policy: PathPolicy): PathVerdict {
 	const hit = policy.protectedPaths.find((p) => within(target, p));
 	if (hit) return { ok: false, why: `it changes a protected file or folder (${hit})` };
+	// Notes never live in hidden folders; .git/hooks, .obsidian/plugins or .vscode can run code.
+	const hidden = target.split(/[\\/]/).find((part) => part.startsWith(".") && part !== "." && part !== "..");
+	if (hidden) return { ok: false, why: `it is in a hidden folder or file (${hidden})` };
 	if (policy.allowed.some((a) => within(target, a))) return { ok: true };
 	return { ok: false, why: "it is outside the vault and the working folder" };
 }
+
+/** Files with keys and passwords: the model may not read them, even when you ask. */
+export function secretPaths(): string[] {
+	const home = realish(homedir());
+	return [
+		join(home, ".subsub", "agent", "auth.json"),
+		join(home, ".pi", "agent", "auth.json"),
+		join(home, ".config", "zotero-local-mcp", "env"),
+		join(home, ".ssh"),
+		join(home, ".aws"),
+		join(home, ".netrc"),
+	];
+}
+
+/** True if reading `target` would read a secret; for grep, also a folder that holds one. */
+export function isSecret(target: string, recursive = false): boolean {
+	return secretPaths().some((p) => within(target, p) || (recursive && within(p, target)));
+}

package/src/prompt.ts

@@ -10,7 +10,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { type SubsubConfig, who } from "./config.ts";
+import { type Mode, type SubsubConfig, who } from "./config.ts";
 import { profileSpec } from "./profiles.ts";
 
 const ROLE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "roles");
@@ -52,17 +52,18 @@ export function fill(text: string, cfg: Pick<SubsubConfig, "userName" | "about"
 		.replace(/[ \t]+\n/g, "\n");
 }
 
-export function roleText(cfg?: Pick<SubsubConfig, "userName" | "about" | "profile">): string {
-	const raw = readIf(join(ROLE_DIR, "assistant.md")) ?? "You are Sub-Sub, a Zotero librarian and research assistant.";
+export function roleText(mode: Mode, cfg?: Pick<SubsubConfig, "userName" | "about" | "profile">): string {
+	const raw = readIf(join(ROLE_DIR, `${mode}.md`)) ?? `You are Sub-Sub, the ${mode}.`;
 	return cfg ? fill(raw, cfg) : raw;
 }
 
-export function systemAddition(cfg: SubsubConfig, cwd: string, libraryChanges: boolean = cfg.libraryChanges): string {
+export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string): string {
 	const user = who(cfg);
-	const parts = ["# Sub-Sub", roleText(cfg)];
-	if (!libraryChanges) {
+	const parts = [`# Sub-Sub: ${mode === "librarian" ? "Librarian" : "Researcher"} mode`, roleText(mode, cfg)];
+	if (cfg.vault) {
 		parts.push(
-			`Library changes are off: you read the library, search, write notes and queue imports. To import, tag or change items, ask ${user} to turn library changes on (/library on, or the switch in the browser view).`,
+			"# The Sub-Sub folder",
+			`The Sub-Sub folder is ${cfg.vault}. Folder names in these instructions (Inbox/, Literature/, Syntheses/, Research/, Zotero/) are inside it. Write notes there with absolute paths, even when the working folder is somewhere else.`,
 		);
 	}
 	const shared = readIf(cfg.sharedRules);

package/src/roles.ts

@@ -1,13 +1,13 @@
 /**
- * Which tools the Assistant may use, and which calls need the user's approval.
+ * Which tools each mode may use, and which calls need the user's approval.
  */
 
-import type { Profile } from "./config.ts";
+import type { Mode, Profile } from "./config.ts";
 import { profileSpec } from "./profiles.ts";
 
 export const FILE_TOOLS = ["read", "edit", "write", "grep", "find", "ls"];
 
-/** Prefixes of the tools that Sub-Sub's servers provide (the gate checks the switch and the profile for these). */
+/** Prefixes of the tools that Sub-Sub's servers provide (the gate checks the mode and the profile for these). */
 export const SERVER_PREFIXES = ["zotero_", "scholar_", "verify_"];
 
 export const ZOTERO_READ = [
@@ -53,42 +53,41 @@ export const ZOTERO_CHECKS = ["tag_audit", "audit_metadata", "find_duplicates",
 	(n) => `zotero_${n}`,
 );
 
+
 export interface ToolOptions {
-	/** Library changes on: the Zotero write tools are offered (each still previewed). */
-	libraryChanges: boolean;
 	profile?: Profile;
 	/** The model test: also the bakeoff_ tools. */
 	bench?: boolean;
 }
 
 /**
- * The Assistant's tools: reading the library, searching, notes and reference
- * checks always; the Zotero write tools when library changes are on. The profile
- * then removes tools.
+ * The tools of a mode. The Librarian manages the library: Zotero tools and files.
+ * The Researcher has the same, plus searches, notes and reference checks. The
+ * profile then removes tools. Every library change is still previewed (gateKind).
  */
-export function toolsFor(registered: string[], opts: ToolOptions): string[] {
+export function toolsFor(mode: Mode, registered: string[], opts: ToolOptions = {}): string[] {
 	const has = new Set(registered);
 	const without = new Set(profileSpec(opts.profile ?? "editor").without);
 	const zotero = registered.filter((n) => n.startsWith("zotero_") && (opts.bench || !n.startsWith("zotero_bakeoff_")));
 	const wanted = [
 		...ZOTERO_READ,
 		...ZOTERO_CHECKS,
-		...(opts.libraryChanges ? zotero : []),
-		...registered.filter((n) => n.startsWith("scholar_") || n.startsWith("verify_")),
+		...zotero,
+		...(mode === "researcher" ? registered.filter((n) => n.startsWith("scholar_") || n.startsWith("verify_")) : []),
 		...FILE_TOOLS,
 	];
 	return [...new Set(wanted)].filter((n) => has.has(n) && !without.has(n));
 }
 
 /** Why a Sub-Sub tool is not available now, or undefined when it is. */
-export function unavailableReason(name: string, registered: string[], opts: ToolOptions): string | undefined {
-	if (toolsFor(registered, opts).includes(name)) return undefined;
+export function unavailableReason(name: string, mode: Mode, registered: string[], opts: ToolOptions = {}): string | undefined {
+	if (toolsFor(mode, registered, opts).includes(name)) return undefined;
 	const profile = opts.profile ?? "editor";
 	if (profileSpec(profile).without.includes(name)) {
 		return `${name} is not part of the ${profileSpec(profile).label} profile. The user can change the profile with /profile.`;
 	}
-	if (!opts.libraryChanges && toolsFor(registered, { ...opts, libraryChanges: true }).includes(name)) {
-		return `${name} changes the library, and library changes are off. The user can turn them on with /library on.`;
+	if (mode === "librarian" && toolsFor("researcher", registered, opts).includes(name)) {
+		return `${name} is part of the Researcher, which also does everything the Librarian does. The user can switch with /researcher.`;
 	}
 	return `${name} is not available.`;
 }

package/src/shortcut.ts

@@ -81,7 +81,7 @@ export function desktopEntry(p: ShortcutPlan): string {
 		"[Desktop Entry]",
 		"Type=Application",
 		"Name=Sub-Sub",
-		"Comment=Zotero librarian and research assistant",
+		"Comment=Research assistant for your Zotero library",
 		`Exec=${desktopQuote(p.node)} ${desktopQuote(p.bin)} web`,
 		`Path=${p.home}`,
 		`Icon=${join(p.packageDir, "assets", "icon.png")}`,
@@ -103,7 +103,7 @@ export function windowsScript(p: ShortcutPlan): string {
 		`  $s.Arguments = ${psQuote(`"${p.bin}" web`)}`,
 		`  $s.WorkingDirectory = ${psQuote(p.home)}`,
 		`  $s.IconLocation = ${psQuote(join(p.packageDir, "assets", "icon.ico"))}`,
-		"  $s.Description = 'Sub-Sub: Zotero librarian and research assistant'",
+		"  $s.Description = 'Sub-Sub: research assistant for your Zotero library'",
 		"  $s.WindowStyle = 7",
 		"  $s.Save()",
 		"  Write-Output (Join-Path $dir 'Sub-Sub.lnk')",

package/src/subsub.ts

@@ -1,15 +1,14 @@
 /**
- * Sub-Sub: a Zotero librarian and research assistant for pi.
+ * Sub-Sub: a research assistant for pi that works from your own Zotero library.
  *
- * - One assistant: it reads the library, searches PubMed, Europe PMC and
- *   OpenAlex, writes notes in the Sub-Sub folder and, with library changes on,
- *   changes the library. /library on|off is the switch (saved in the settings).
+ * - Two modes: the Librarian manages the library (Zotero tools only); the
+ *   Researcher does the same and also searches PubMed, Europe PMC and OpenAlex
+ *   and writes notes. Each mode can have its own model.
  * - An approval gate: every library change is previewed by the server (dry run)
  *   and shown to the user; nothing is applied without a yes.
  * - Profiles (reader, scholar, author, editor) set what Sub-Sub writes and which
  *   tools it offers; /profile changes it.
- * - Commands: /library, /profile, /subsub, /history, /undo. /librarian and
- *   /researcher (the two modes before 0.10) turn library changes on and off.
+ * - Commands: /librarian, /researcher, /profile, /subsub, /history, /undo.
  * - Add-on: with "addons": ["starbuck"], Starbuck runs as a third server
  *   ("verify") for reference checks.
  *
@@ -29,6 +28,7 @@ import {
 	loadConfig,
 	parseEnvFile,
 	type Profile,
+	type Mode,
 	saveConfig,
 	serverCommand,
 	starbuckCommand,
@@ -39,12 +39,14 @@ import {
 import { profileList, profileSpec, promptBlocked } from "./profiles.ts";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.ts";
 import { applyEdits, checkLiteratureNote } from "./notes.ts";
-import { buildPolicy, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
+import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview } from "./preview.ts";
 import { headerLines, type LibraryState, paintPreview, QUOTES, type Scheme, schemeFromAnsi, themeName } from "./look.ts";
 import { systemAddition } from "./prompt.ts";
 import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason } from "./roles.ts";
 
+const MODE_ENTRY = "subsub-mode";
+
 export interface SubsubDeps {
 	config?: SubsubConfig;
 	/** A ready bridge (tests). When given, Sub-Sub does not start or stop servers. */
@@ -127,12 +129,12 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 
 	if (deps.bridge) registerTools(deps.bridge);
 
-	pi.registerFlag("read-only", { description: "Start Sub-Sub with library changes off (this run only)", type: "boolean", default: false });
-	pi.registerFlag("librarian", { description: "Start Sub-Sub with library changes on (this run only)", type: "boolean", default: false });
+	pi.registerFlag("librarian", { description: "Start Sub-Sub in the Librarian mode", type: "boolean", default: false });
+	pi.registerFlag("researcher", { description: "Start Sub-Sub in the Researcher mode", type: "boolean", default: false });
 
-	let libraryChanges = cfg.libraryChanges;
+	let mode: Mode = cfg.defaultMode;
 	const benchRun = Boolean(process.env.SUBSUB_BENCH_OUT);
-	const toolOpts = () => ({ libraryChanges, profile, bench: benchRun });
+	const toolOpts = () => ({ profile, bench: benchRun });
 	let profile: Profile = cfg.profile;
 	const user = who(cfg);
 	/** True when started with the `subsub` command (not as a package inside plain pi). */
@@ -154,7 +156,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		if (!webView || !ctx || ctx.mode !== "rpc") return;
 		const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
 		const state = {
-			libraryChanges,
+			mode,
 			profile,
 			profileLabel: profileSpec(profile).label,
 			model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : null,
@@ -221,7 +223,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 					const th = ctx.ui.theme;
 					return headerLines({
 						version,
-						libraryChanges,
+						mode,
 						profile: profileSpec(profile).label,
 						model: modelId,
 						library,
@@ -244,37 +246,28 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	function status(ctx: ExtensionContext): void {
 		modelId = ctx.model ? `${ctx.model.id}` : "no model";
 		const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
-		const lib = libraryChanges ? "library changes on" : "read only";
-		ctx.ui.setStatus("subsub", `Sub-Sub: ${lib} | ${profileSpec(profile).label} | ${modelId}${down.length ? ` | not running: ${down.join(", ")}` : ""}`);
-		if (standalone) ctx.ui.setTitle(libraryChanges ? "Sub-Sub" : "Sub-Sub (read only)");
+		ctx.ui.setStatus("subsub", `Sub-Sub: ${mode} | ${profileSpec(profile).label} | ${modelId}${down.length ? ` | not running: ${down.join(", ")}` : ""}`);
+		if (standalone) ctx.ui.setTitle(`Sub-Sub: ${mode}`);
 		headerTui?.requestRender();
 		webCtx = ctx;
 		emitWeb();
 	}
 
-	/** Set the tools for the switch and the profile; save the switch when asked. */
-	function applyLibrary(ctx: ExtensionContext, on: boolean, save: boolean): void {
-		libraryChanges = on;
-		pi.setActiveTools(toolsFor(registered(), toolOpts()));
-		if (save) {
-			try {
-				saveConfig({ libraryChanges: on });
-			} catch (err) {
-				ctx.ui.notify(`Sub-Sub: the setting was not saved: ${(err as Error).message}`, "warning");
-			}
+	/** Set the mode's tools and, unless `switchModel` is false, the mode's model. */
+	async function applyMode(ctx: ExtensionContext, next: Mode, remember: boolean, switchModel = true): Promise<void> {
+		mode = next;
+		pi.setActiveTools(toolsFor(mode, registered(), toolOpts()));
+		const spec = cfg.models[mode];
+		if (spec && switchModel) {
+			const i = spec.indexOf("/");
+			const model = i > 0 ? ctx.modelRegistry.find(spec.slice(0, i), spec.slice(i + 1)) : undefined;
+			const ok = model ? await pi.setModel(model) : false;
+			if (!ok) ctx.ui.notify(`Sub-Sub: cannot use ${spec} (unknown model or no key); keeping the current model.`, "warning");
 		}
+		if (remember) pi.appendEntry(MODE_ENTRY, { mode });
 		status(ctx);
 	}
 
-	async function applyModel(ctx: ExtensionContext): Promise<void> {
-		const spec = cfg.model;
-		if (!spec) return;
-		const i = spec.indexOf("/");
-		const model = i > 0 ? ctx.modelRegistry.find(spec.slice(0, i), spec.slice(i + 1)) : undefined;
-		const ok = model ? await pi.setModel(model) : false;
-		if (!ok) ctx.ui.notify(`Sub-Sub: cannot use ${spec} (unknown model or no key); keeping the current model.`, "warning");
-	}
-
 	pi.on("session_start", async (_event, ctx) => {
 		if (!bridge) {
 			const b = new Bridge();
@@ -282,12 +275,17 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			bridge = b;
 			registerTools(b);
 		}
+		let restored: Mode | undefined;
+		let modelChosen = false; // the session already has a model: a resumed conversation keeps it
+		for (const e of ctx.sessionManager.getBranch() as Array<{ type?: string; customType?: string; data?: { mode?: unknown } }>) {
+			const m = e.customType === MODE_ENTRY ? e.data?.mode : undefined;
+			if (m === "librarian" || m === "researcher") restored = m;
+			if (e.type === "model_change") modelChosen = true;
+		}
 		// Judge light or dark before Sub-Sub changes the theme.
 		if (lookOn(ctx)) scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
-		await applyModel(ctx);
 		applyTheme(ctx);
-		// The flags change this run only; the saved setting stays.
-		applyLibrary(ctx, pi.getFlag("read-only") ? false : pi.getFlag("librarian") ? true : cfg.libraryChanges, false);
+		await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : pi.getFlag("researcher") ? "researcher" : cfg.defaultMode), false, !modelChosen);
 		if (lookOn(ctx)) {
 			setHeader(ctx);
 			void refreshLibrary();
@@ -306,11 +304,29 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		await b?.close();
 	});
 
+	/** Prompt commands for the Researcher; the Librarian has the library ones (tag-batch, clean-tags, import-queue). */
+	const RESEARCH_PROMPTS = ["lit", "compare", "lit-note", "synthesis", "gaps", "manuscript", "verify", "review", "alert", "request-copy", "digest"];
+
+	// /tree moves to another branch: take that branch's mode (pi restores its model itself).
+	pi.on("session_tree", async (_event, ctx) => {
+		let m: Mode | undefined;
+		for (const e of ctx.sessionManager.getBranch() as Array<{ customType?: string; data?: { mode?: unknown } }>) {
+			const x = e.customType === MODE_ENTRY ? e.data?.mode : undefined;
+			if (x === "librarian" || x === "researcher") m = x;
+		}
+		if (m && m !== mode) await applyMode(ctx, m, false, false);
+	});
+
 	pi.on("model_select", async (_event, ctx) => status(ctx));
 
 	// Prompt commands that the profile does not run (/lit for Reader, /review for Reader and Scholar).
 	// The input event comes before pi expands a prompt template.
 	pi.on("input", async (event, ctx) => {
+		const cmd = /^\/([\w-]+)(?:\s|$)/.exec(event.text.trim())?.[1];
+		if (mode === "librarian" && cmd && RESEARCH_PROMPTS.includes(cmd)) {
+			ctx.ui.notify(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, "warning");
+			return { action: "handled" };
+		}
 		const why = promptBlocked(event.text, profile);
 		if (!why) return { action: "continue" };
 		ctx.ui.notify(`Sub-Sub: ${why}`, "warning");
@@ -318,7 +334,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	});
 
 	pi.on("before_agent_start", async (event, ctx) => ({
-		systemPrompt: `${event.systemPrompt}\n\n${systemAddition({ ...cfg, profile }, ctx.cwd, libraryChanges)}`,
+		systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, { ...cfg, profile }, ctx.cwd)}`,
 	}));
 
 	/** Model test (subsub-bench): record every change instead of asking, and apply none. */
@@ -333,12 +349,15 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		if (schema) coerceArgs(schema, input);
 		resolvePathArgs(name, input, (p) => normalizeToolPath(p, ctx.cwd));
 		if (SERVER_PREFIXES.some((p) => name.startsWith(p))) {
-			const why = unavailableReason(name, registered(), toolOpts());
+			const why = unavailableReason(name, mode, registered(), toolOpts());
 			if (why) {
 				if (benchOut) record({ kind: "wrong_mode", tool: name, input });
 				return { block: true, reason: why };
 			}
 		}
+		if (["read", "grep", "find", "ls"].includes(name) && typeof input.path === "string" && isSecret(normalizeToolPath(input.path, ctx.cwd), name === "grep")) {
+			return { block: true, reason: "That file holds keys or passwords. Sub-Sub does not read it." };
+		}
 		if (name.startsWith("verify_")) return verifyGate(name, input, ctx);
 		const kind = benchOut && name === "scholar_queue_imports" ? "confirm" : gateKind(name, input);
 		if (!kind) return undefined;
@@ -447,39 +466,19 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		};
 	}
 
-	const libraryNote = (on: boolean) =>
-		on
-			? "Sub-Sub: library changes on. Every change shows a preview first."
-			: "Sub-Sub: library changes off. Sub-Sub reads, searches and writes notes; it does not change the library.";
-
-	pi.registerCommand("library", {
-		description: "Sub-Sub: turn library changes on or off (/library on, /library off)",
-		handler: async (args, ctx) => {
-			const a = args.trim().toLowerCase();
-			const on = a === "on" ? true : a === "off" ? false : a === "" ? !libraryChanges : undefined;
-			if (on === undefined) {
-				ctx.ui.notify("Type /library on or /library off.", "warning");
-				return;
-			}
-			applyLibrary(ctx, on, true);
-			ctx.ui.notify(libraryNote(on), "info");
-		},
-	});
-
-	// The two modes before 0.10, kept so that old habits and notes still work.
 	pi.registerCommand("librarian", {
-		description: "Sub-Sub: same as /library on",
+		description: "Sub-Sub: switch to the Librarian (manages the library: tags, imports, metadata, PDFs)",
 		handler: async (_args, ctx) => {
-			applyLibrary(ctx, true, true);
-			ctx.ui.notify(`${libraryNote(true)} (/librarian is now /library on.)`, "info");
+			await applyMode(ctx, "librarian", true);
+			ctx.ui.notify("Sub-Sub: Librarian mode. For searches and notes, switch to /researcher.", "info");
 		},
 	});
 
 	pi.registerCommand("researcher", {
-		description: "Sub-Sub: same as /library off",
+		description: "Sub-Sub: switch to the Researcher (searches, notes, reviews, and everything the Librarian does)",
 		handler: async (_args, ctx) => {
-			applyLibrary(ctx, false, true);
-			ctx.ui.notify(`${libraryNote(false)} (/researcher is now /library off.)`, "info");
+			await applyMode(ctx, "researcher", true);
+			ctx.ui.notify("Sub-Sub: Researcher mode. It searches, writes notes and also changes the library, with a preview.", "info");
 		},
 	});
 
@@ -502,7 +501,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			} catch (err) {
 				saved = ` Not saved: ${(err as Error).message}`;
 			}
-			applyLibrary(ctx, libraryChanges, false);
+			await applyMode(ctx, mode, false, false);
 			ctx.ui.notify(`Sub-Sub: ${profileSpec(profile).label} profile (${profileSpec(profile).summary}).${saved}`, "info");
 		},
 	});
@@ -510,7 +509,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	pi.registerCommand("subsub", {
 		description: "Sub-Sub: Zotero connection and library overview",
 		handler: async (_args, ctx) => {
-			const lines = [`Library changes: ${libraryChanges ? "on" : "off"}. Profile: ${profileSpec(profile).label}. Model: ${ctx.model?.id ?? "none"}.`];
+			const lines = [`Mode: ${mode}. Profile: ${profileSpec(profile).label}. Model: ${ctx.model?.id ?? "none"}.`];
 			if (!bridge) {
 				ctx.ui.notify(`${lines[0]}\nThe Zotero servers are not running. Try /reload.`, "warning");
 				return;