@falkenslab/agent-kit 0.20.0 → 0.22.0

package/dist/core/externalExtensions.js

@@ -9,7 +9,52 @@ import { getLanguage } from "./messages/index.js";
 import { truncate } from "./toolLabels.js";
 import { agentKitVersion } from "./version.js";
 import { outsideArchive } from "./packaged.js";
+import { extensionSecretsPath, missingOptions, optionsNamed, parseOptionValue, parseUserConfig, readOptionValues, removeSecrets, storeOptionValues } from "./extensionOptions.js";
+import { isTrusted } from "./workspaceTrust.js";
+import { cachedPackageDir, cachedPackageProblem, cachePackage, npxServer, packageCacheDir, packageSpec } from "./npxPackages.js";
 export const LOCK_FILE = "extensions.lock.json";
+/**
+ * An installed extension's data folder: `${CLAUDE_PLUGIN_DATA}` in its servers' arguments and
+ * variables (a browser profile, a cache), in its scope, outside its plugin and its hash, so it's
+ * kept across sessions and updates. Created when a session starts it; removing the extension
+ * asks before deleting it.
+ */
+export function extensionDataDir(scopeDir, name) {
+    return path.join(scopeDir, ".data", name);
+}
+/**
+ * Where a scope keeps what's the person's, not the workspace's: its extensions' data and secrets
+ * (#57). The agent's scope, its own folder; a project's, a folder of its own in the agent's
+ * (`<agent scope>/.projects/<project>-<hash>/`), so nothing private travels with a project. An
+ * agent without a scope of its own keeps it in the project's.
+ */
+export function scopePrivateDir(dirs, scope) {
+    const scopeDir = dirs[scope];
+    if (!scopeDir)
+        return undefined;
+    if (scope === "agent" || !dirs.agent)
+        return scopeDir;
+    const resolved = path.resolve(scopeDir);
+    const key = createHash("sha256").update(resolved.toLowerCase()).digest("hex").slice(0, 12);
+    return path.join(dirs.agent, ".projects", `${path.basename(path.dirname(resolved)) || "project"}-${key}`);
+}
+/** The agent's store of extensions' code, by content (#57): where a project's scope keeps its extensions' code. */
+export function codeStoreDir(dirs) {
+    return dirs.agent ? path.join(dirs.agent, ".store") : undefined;
+}
+/** Where a stored extension's code is: by its name and its files' hash. */
+export function storedCodeDir(store, name, sha256) {
+    return path.join(store, name, sha256.slice(0, 16));
+}
+/**
+ * How an install into `scope` is done: its npx packages into the agent's cache, and a project's
+ * code into the agent's store when the agent has a scope of its own.
+ */
+export function installTarget(dirs, scope) {
+    const packages = packageCacheDir(dirs);
+    const store = scope === "project" ? codeStoreDir(dirs) : undefined;
+    return { ...(packages ? { packages } : {}), ...(store ? { store } : {}) };
+}
 /** A scope's lock: its extensions by name. */
 export async function readLock(scopeDir) {
     try {
@@ -39,7 +84,9 @@ export async function readExternalManifest(dir) {
     const name = raw.name;
     if (typeof name !== "string" || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name))
         throw new Error(`${file}: "name" must be kebab-case.`);
-    const kit = (raw["agent-kit"] ?? {});
+    // The kit's data, where Claude Code keeps a plugin's own (`metadata`, which it doesn't read): a
+    // top-level key would fail `claude plugin validate --strict` (#55).
+    const kit = (raw.metadata?.["agent-kit"] ?? {});
     const text = (key) => (typeof raw[key] === "string" ? { [key]: raw[key] } : {});
     const author = raw.author;
     // `repository` may be a URL or `{ url }`, as in package.json.
@@ -60,11 +107,21 @@ export async function readExternalManifest(dir) {
         ...(kit.kit ? { kit: kit.kit } : {}),
         needs: Array.isArray(kit.needs) ? kit.needs.filter((program) => typeof program === "string") : [],
         servers: await pluginServers(dir, raw),
-        readOnlyTools: kit.readOnlyTools ?? [],
+        ...(Array.isArray(kit.readOnlyTools) ? { readOnlyTools: kit.readOnlyTools.filter((tool) => typeof tool === "string") } : {}),
         labels: kit.labels ?? {},
         ...(kit.help ? { help: kit.help } : {}),
+        userConfig: parseUserConfig(raw.userConfig),
+        ...catalogLook(kit.catalog),
     };
 }
+/** A manifest's `catalog` (#59): only its `logo` and `banner`, when they're paths. */
+function catalogLook(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const { logo, banner } = raw;
+    const look = { ...(typeof logo === "string" ? { logo } : {}), ...(typeof banner === "string" ? { banner } : {}) };
+    return Object.keys(look).length ? { catalog: look } : {};
+}
 /**
  * A plugin's MCP servers, where Claude Code looks for them: `mcpServers` in `plugin.json` (inline,
  * or a path to a JSON file), else `.mcp.json` at its root, with or without the `mcpServers` key.
@@ -99,29 +156,56 @@ async function pluginServers(dir, raw) {
     }
     return servers;
 }
-/** `${CLAUDE_PLUGIN_ROOT}` (the extension's folder) and `${VAR}` (the agent's variable) in a server's values. */
-function expand(value, root) {
-    return value.replace(/\$\{(\w+)\}/g, (_, name) => (name === "CLAUDE_PLUGIN_ROOT" ? root : (process.env[name] ?? "")));
+/** `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}` and `${VAR}` (the agent's variable) in a server's values. */
+function expand(value, folders) {
+    return value.replace(/\$\{(\w+)\}/g, (_, name) => name === "CLAUDE_PLUGIN_ROOT" ? folders.root : name === "CLAUDE_PLUGIN_DATA" ? folders.data : (process.env[name] ?? ""));
 }
 /**
- * Why one of an extension's servers can't run through the launcher (only Node, its script
- * first, inside the extension), or how the kit starts it.
+ * Why one of an extension's servers can't run through the launcher (Node, its script first,
+ * inside the extension; or npx with a package at an exact version, from the cache), or how the
+ * kit starts it.
  */
-function serverLaunch(name, server, root) {
+function serverLaunch(name, server, folders, packages = {}) {
+    const { root } = folders;
+    // Its folders as variables too, as Claude Code gives them to a plugin's servers.
+    const declared = Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(String(value), folders)]));
+    const env = { CLAUDE_PLUGIN_ROOT: root, CLAUDE_PLUGIN_DATA: folders.data, ...declared };
+    const npx = npxServer(server);
+    if (typeof npx === "string")
+        return `${npx} (its server "${name}")`;
+    if (npx) {
+        const locked = packages.locked?.[packageSpec(npx)];
+        if (!packages.cache || !locked)
+            return `runs ${packageSpec(npx)}, which wasn't fetched when it was installed: install it again`;
+        const entry = path.join(cachedPackageDir(packages.cache, npx.name, npx.version), locked.bin);
+        return { entry, args: npx.args.map((arg) => expand(arg, folders)), env };
+    }
     if (!/^node(\.exe)?$/i.test(path.basename(server.command)))
-        return `runs its server "${name}" with "${server.command}": only Node servers can be installed`;
-    const [script, ...args] = (server.args ?? []).map((arg) => expand(arg, root));
+        return `runs its server "${name}" with "${server.command}": only Node servers, or npx with a package's exact version, can be installed`;
+    const [script, ...args] = (server.args ?? []).map((arg) => expand(arg, folders));
     if (!script)
         return `gives its server "${name}" no script to run`;
     const entry = path.resolve(root, script);
     if (path.relative(root, entry).startsWith(".."))
         return `runs its server "${name}" from outside its folder (${script})`;
-    return { entry, args, env: Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(String(value), root)])) };
+    return { entry, args, env };
 }
-/** Why an extension's servers can't run, or nothing: each must be Node, with its script there. */
-async function serversProblem(manifest, root) {
+/**
+ * Why an extension's servers can't run, or nothing: each Node with its script there, or npx with
+ * a package at an exact version (in the cache, once `packages` is given: when it loads).
+ */
+async function serversProblem(manifest, root, packages) {
     for (const [name, server] of Object.entries(manifest.servers)) {
-        const launch = serverLaunch(name, server, root);
+        const npx = npxServer(server);
+        if (typeof npx === "string")
+            return `${npx} (its server "${name}")`;
+        if (npx) {
+            const problem = packages && (await cachedPackageProblem(packages.cache, npx, packages.locked?.[packageSpec(npx)]));
+            if (problem)
+                return problem;
+            continue;
+        }
+        const launch = serverLaunch(name, server, { root, data: "" });
         if (typeof launch === "string")
             return launch;
         if (!(await stat(launch.entry).catch(() => null))?.isFile())
@@ -129,7 +213,28 @@ async function serversProblem(manifest, root) {
     }
     return undefined;
 }
-/** SHA-256 over an extension's files (their paths and contents, in order), `.git` aside. */
+/** Fetches the packages an extension's npx servers run into the cache (#54), as its lock records them. */
+async function fetchServerPackages(manifest, cache) {
+    const packages = {};
+    for (const server of Object.values(manifest.servers)) {
+        const npx = npxServer(server);
+        if (!npx || typeof npx === "string")
+            continue;
+        packages[packageSpec(npx)] = await cachePackage(cache, npx.name, npx.version);
+    }
+    return packages;
+}
+/** A text file's bytes with CRLF as LF (latin1 maps each byte to itself); a binary one's (a NUL byte in it) as they are. */
+function withoutCarriageReturns(bytes) {
+    if (bytes.includes(0) || !bytes.includes(13))
+        return bytes;
+    return Buffer.from(bytes.toString("latin1").replace(/\r\n/g, "\n"), "latin1");
+}
+/**
+ * SHA-256 over an extension's files (their paths and contents, in order), `.git` aside. A text
+ * file's line endings don't count (CRLF is taken as LF): git checks the same commit out with CRLF
+ * on one computer and LF on another, and a workspace's lock must match on both (#57).
+ */
 export async function hashExtension(dir) {
     const hash = createHash("sha256");
     async function walk(relative) {
@@ -139,7 +244,7 @@ export async function hashExtension(dir) {
             if (entry.isDirectory())
                 await walk(child);
             else if (entry.isFile())
-                hash.update(`${child}\0`).update(await readFile(path.join(dir, child))).update("\0");
+                hash.update(`${child}\0`).update(withoutCarriageReturns(await readFile(path.join(dir, child)))).update("\0");
         }
     }
     await walk("");
@@ -187,10 +292,12 @@ export async function listInstalled(dirs) {
         const scopeDir = dirs[scope];
         if (!scopeDir)
             continue;
+        const privateDir = scopePrivateDir(dirs, scope);
+        const store = codeStoreDir(dirs);
         for (const [name, lock] of Object.entries(await readLock(scopeDir))) {
-            const dir = path.join(scopeDir, name);
+            const dir = lock.linked ? lock.source : lock.stored && store ? storedCodeDir(store, name, lock.sha256) : path.join(scopeDir, name);
             const manifest = await readExternalManifest(dir).catch(() => undefined);
-            installed.push({ name, scope, dir, lock, shadowed: installed.some((other) => other.name === name), ...(manifest ? { manifest } : {}) });
+            installed.push({ name, scope, scopeDir, dir, dataDir: extensionDataDir(privateDir, name), privateDir, lock, shadowed: installed.some((other) => other.name === name), ...(manifest ? { manifest } : {}) });
         }
     }
     return installed;
@@ -213,46 +320,84 @@ function manifestToolLabels(manifest) {
     }));
 }
 /** The extension an installed one makes: its servers started through the launcher, its rules from its manifest. */
-function externalExtension(installed, manifest) {
+function externalExtension(installed, manifest, cache) {
     return {
         name: manifest.name,
         plugin: installed.dir,
         external: true,
+        installedIn: installed.scopeDir,
         async contribute() {
             const servers = {};
+            if (Object.keys(manifest.servers).length)
+                await mkdir(installed.dataDir, { recursive: true });
             for (const [name, server] of Object.entries(manifest.servers)) {
-                const launch = serverLaunch(name, server, installed.dir);
+                const launch = serverLaunch(name, server, { root: installed.dir, data: installed.dataDir }, { cache, locked: installed.lock.packages });
                 if (typeof launch === "string")
                     continue; // checked when it loaded
                 // Its `env` reaches it (the SDK merges it with the agent's); the launcher removes the rest.
                 // Inside Electron, process.execPath is the app itself: ELECTRON_RUN_AS_NODE makes it run
                 // the launcher as Node (the launcher removes it, with the rest, once it runs).
                 const env = process.versions.electron ? { ...launch.env, ELECTRON_RUN_AS_NODE: "1" } : launch.env;
-                servers[name] = { type: "stdio", command: process.execPath, args: [extensionLauncherPath(), launch.entry, JSON.stringify(Object.keys(launch.env)), ...launch.args], env };
+                // The launcher's own spec: the variables it keeps, and where its options' values are, read
+                // when it starts the server, so a changed value reaches a server started again (#55).
+                const spec = {
+                    keep: Object.keys(launch.env),
+                    ...(Object.keys(manifest.userConfig).length
+                        ? { options: { lock: path.join(installed.scopeDir, LOCK_FILE), secrets: extensionSecretsPath(installed.privateDir, installed.name), name: installed.name, defaults: optionDefaults(manifest.userConfig) } }
+                        : {}),
+                };
+                servers[name] = { type: "stdio", command: process.execPath, args: [extensionLauncherPath(), launch.entry, JSON.stringify(spec), ...launch.args], env };
             }
             return {
                 mcpServers: servers,
-                readOnlyTools: Object.keys(manifest.servers).flatMap((server) => manifest.readOnlyTools.map((tool) => `mcp__${server}__${tool}`)),
+                // Its manifest's list, or its servers' own word: the server is the code the kit trusts
+                // least, so its hints only fill the list's absence (ADR-025).
+                ...(manifest.readOnlyTools
+                    ? { readOnlyTools: Object.keys(manifest.servers).flatMap((server) => manifest.readOnlyTools.map((tool) => `mcp__${server}__${tool}`)) }
+                    : { readOnlyTools: [], readOnlyHintServers: Object.keys(servers) }),
                 toolLabels: manifestToolLabels(manifest),
                 ...(manifest.help ? { helpLines: [manifest.help] } : {}),
             };
         },
     };
 }
+/** Its options' defaults, for the launcher. */
+function optionDefaults(declared) {
+    return Object.fromEntries(Object.entries(declared).flatMap(([key, option]) => (option.default === undefined ? [] : [[key, option.default]])));
+}
+/** Why its options keep it from running (a server naming one it doesn't declare, a required one without a value), or nothing. */
+function optionsProblem(manifest, values) {
+    const named = optionsNamed(Object.values(manifest.servers).flatMap((server) => [server.command, ...(server.args ?? []), ...Object.values(server.env ?? {}).map(String)]));
+    const undeclared = named.filter((key) => !manifest.userConfig[key]);
+    if (undeclared.length)
+        return `names ${undeclared.map((key) => "${user_config." + key + "}").join(", ")}, which its userConfig doesn't declare`;
+    const missing = missingOptions(manifest.userConfig, values);
+    if (missing.length)
+        return `needs ${missing.map((key) => `${key} (${manifest.userConfig[key].title})`).join(", ")} set: \`extension config ${manifest.name} ${missing[0]}=<value>\``;
+    return undefined;
+}
 /** The installed extensions a session runs with, and those it can't (with why). Disabled ones are neither. */
 export async function loadExternalExtensions(dirs) {
     const extensions = [];
     const off = [];
+    const untrusted = [];
+    const cache = packageCacheDir(dirs);
     for (const installed of await listInstalled(dirs)) {
         if (installed.shadowed || !installed.lock.enabled)
             continue;
-        const reason = await problem(installed);
+        // A workspace's own: only once the person trusts it there (#57); the agent's never asks.
+        if (installed.scope === "project" && dirs.agent && !(await isTrusted(dirs.agent, installed.scopeDir, installed.name, installed.lock))) {
+            untrusted.push(installed);
+            off.push({ name: installed.name, reason: "comes with this workspace and isn't trusted here yet: `extension trust`, or the chat asks" });
+            continue;
+        }
+        const reason = await problem(installed, cache);
         if (typeof reason === "string")
             off.push({ name: installed.name, reason });
         else
-            extensions.push(externalExtension(installed, reason));
+            extensions.push(externalExtension(installed, reason, cache));
     }
-    return { extensions, off };
+    return { extensions, off, untrusted };
 }
 /** Why an installed extension can't load, or its manifest when it can. */
 /** Whether a program is on the `PATH`, as a shell would find it (with `PATHEXT`'s extensions on Windows). */
@@ -268,10 +413,12 @@ export async function onPath(program, env = process.env) {
     }
     return false;
 }
-async function problem(installed) {
+async function problem(installed, cache) {
     let manifest;
     try {
-        if ((await hashExtension(installed.dir)) !== installed.lock.sha256)
+        if (installed.lock.stored && !(await stat(installed.dir).catch(() => null))?.isDirectory())
+            return "isn't on this computer yet (its workspace says which version it uses): `extension restore` gets it";
+        if (!installed.lock.linked && (await hashExtension(installed.dir)) !== installed.lock.sha256)
             return "has files that changed since it was installed: install it again to trust them";
         manifest = await readExternalManifest(installed.dir);
     }
@@ -288,7 +435,10 @@ async function problem(installed) {
             missing.push(program);
     if (missing.length)
         return `needs ${missing.join(", ")}, which ${missing.length === 1 ? "isn't" : "aren't"} on this computer (on the PATH)`;
-    return (await serversProblem(manifest, installed.dir)) ?? manifest;
+    const options = optionsProblem(manifest, await readOptionValues(installed.privateDir, installed.name, manifest.userConfig, installed.lock.options));
+    if (options)
+        return options;
+    return (await serversProblem(manifest, installed.dir, { cache, locked: installed.lock.packages })) ?? manifest;
 }
 const exec = promisify(execFile);
 /** Whether `source` names a git repository rather than a folder. */
@@ -300,9 +450,14 @@ export function isGitSource(source) {
  * a commit, and `subdir` for one inside it): copies its files (never runs a script), checks its
  * manifest, and locks it, enabled, with the marketplace it came from when it did (`origin`, for a
  * temporary folder, is what the lock says it came from). An extension with the same name in that
- * scope is replaced.
+ * scope is replaced; its data folder stays. With `link`, a folder is registered where it is
+ * instead, to develop it: not copied, and its files not checked. The packages its npx servers
+ * run are fetched into `packages` (#54), the agent's package cache (`packageCacheDir()`; by
+ * default the scope's).
  */
 export async function addExtension(source, scopeDir, options = {}) {
+    if (options.link && isGitSource(source))
+        throw new Error("Only a folder can be linked: a git repository is installed as a copy.");
     let from = path.resolve(source);
     let commit;
     let clone;
@@ -326,16 +481,44 @@ export async function addExtension(source, scopeDir, options = {}) {
         if (servers)
             throw new Error(`${manifest.name} can't be installed: it ${servers}.`);
         const target = path.join(scopeDir, manifest.name);
+        // Replacing what's installed there would delete the source itself.
+        if (path.resolve(from) === path.resolve(target))
+            throw new Error(`${from} is where ${manifest.name} is installed: install it from another folder.`);
+        const packages = await fetchServerPackages(manifest, options.packages ?? path.join(scopeDir, ".npm"));
+        const locked = Object.keys(packages).length ? { packages } : {};
         const lock = await readLock(scopeDir);
         const replaced = Boolean(lock[manifest.name]);
+        // Reinstalled, it keeps the values it had for the options it still declares, as it keeps its data.
+        const kept = Object.fromEntries(Object.entries(lock[manifest.name]?.options ?? {}).filter(([key]) => manifest.userConfig[key] && !manifest.userConfig[key].sensitive));
+        if (Object.keys(kept).length)
+            locked.options = kept;
         await rm(target, { recursive: true, force: true });
         await mkdir(scopeDir, { recursive: true });
+        const origin = options.origin ?? (isGitSource(source) ? source : from);
+        const provenance = { ...(commit ? { commit } : {}), ...(options.subdir ? { subdir: options.subdir } : {}), ...(options.marketplace ? { marketplace: options.marketplace } : {}) };
+        if (options.store && !options.link) {
+            // By content, in the agent's store: two workspaces with the same version share one copy.
+            const sha256 = await hashExtension(from);
+            const stored = storedCodeDir(options.store, manifest.name, sha256);
+            if (!(await stat(stored).catch(() => null))?.isDirectory() || (await hashExtension(stored)) !== sha256) {
+                await rm(stored, { recursive: true, force: true });
+                await cp(from, stored, { recursive: true, filter: (file) => path.basename(file) !== ".git" });
+            }
+            lock[manifest.name] = { source: origin, ...provenance, sha256, stored: true, ...locked, enabled: true, installed: new Date().toISOString() };
+            await writeLock(scopeDir, lock);
+            return { name: manifest.name, replaced, ...(commit ? { commit } : {}) };
+        }
+        if (options.link) {
+            lock[manifest.name] = { source: from, linked: true, sha256: "", ...locked, enabled: true, installed: new Date().toISOString() };
+            await writeLock(scopeDir, lock);
+            return { name: manifest.name, replaced };
+        }
         await cp(from, target, { recursive: true, filter: (file) => path.basename(file) !== ".git" });
         lock[manifest.name] = {
-            source: options.origin ?? (isGitSource(source) ? `${source}${options.subdir ? ` (${options.subdir})` : ""}` : from),
-            ...(commit ? { commit } : {}),
-            ...(options.marketplace ? { marketplace: options.marketplace } : {}),
+            source: origin,
+            ...provenance,
             sha256: await hashExtension(target),
+            ...locked,
             enabled: true,
             installed: new Date().toISOString(),
         };
@@ -347,16 +530,36 @@ export async function addExtension(source, scopeDir, options = {}) {
             await rm(clone, { recursive: true, force: true });
     }
 }
-/** Removes an extension from a scope (its files and its lock entry); false when it wasn't there. */
-export async function removeExtension(scopeDir, name) {
+/**
+ * Removes an extension from a scope (its files and its lock entry; a linked one's folder is left
+ * where it is), and its data folder with `deleteData`; false when it wasn't there.
+ */
+export async function removeExtension(scopeDir, name, options = {}) {
+    const privateDir = options.privateDir ?? scopeDir;
     const lock = await readLock(scopeDir);
     if (!lock[name])
         return false;
     delete lock[name];
     await rm(path.join(scopeDir, name), { recursive: true, force: true });
+    // A stored one's code stays in the store: another workspace may use the same version.
+    if (options.deleteData)
+        await rm(extensionDataDir(privateDir, name), { recursive: true, force: true });
+    await removeSecrets(privateDir, name);
     await writeLock(scopeDir, lock);
     return true;
 }
+/** The size in bytes of the files under `dir` (0 when it doesn't exist). */
+export async function folderSize(dir) {
+    let size = 0;
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            size += await folderSize(full);
+        else if (entry.isFile())
+            size += (await stat(full)).size;
+    }
+    return size;
+}
 /** Enables or disables an installed extension in a scope; false when it isn't there. */
 export async function setExtensionEnabled(scopeDir, name, enabled) {
     const lock = await readLock(scopeDir);
@@ -366,3 +569,46 @@ export async function setExtensionEnabled(scopeDir, name, enabled) {
     await writeLock(scopeDir, lock);
     return true;
 }
+/**
+ * Sets an installed extension's options (#55), each from what the person typed (`undefined`
+ * clears it), checked against its `userConfig`: sensitive ones into the scope's secrets, the rest
+ * into its lock. A running session's servers take them when they start again.
+ */
+export async function setExtensionOptions(where, name, typed) {
+    // A scope's folder (the agent's, whose code and secrets are in it), or an installed one, which knows where they are.
+    const scopeDir = typeof where === "string" ? where : where.scopeDir;
+    const privateDir = typeof where === "string" ? where : where.privateDir;
+    const lock = await readLock(scopeDir);
+    const entry = lock[name];
+    if (!entry)
+        throw new Error(`${name} isn't installed in ${scopeDir}.`);
+    const manifest = (typeof where === "string" ? undefined : where.manifest) ?? (await readExternalManifest(entry.linked ? entry.source : path.join(scopeDir, name)));
+    const changes = {};
+    for (const [key, text] of Object.entries(typed)) {
+        const option = manifest.userConfig[key];
+        if (!option)
+            throw new Error(`${name} has no option "${key}"${Object.keys(manifest.userConfig).length ? `: it has ${Object.keys(manifest.userConfig).join(", ")}` : ""}.`);
+        try {
+            changes[key] = text === undefined ? undefined : parseOptionValue(option, text);
+        }
+        catch (error) {
+            throw new Error(`${key}: ${error instanceof Error ? error.message : String(error)}.`, { cause: error });
+        }
+    }
+    const options = await storeOptionValues(privateDir, name, manifest.userConfig, entry.options ?? {}, changes);
+    lock[name] = { ...entry, options };
+    if (!Object.keys(options).length)
+        delete lock[name].options;
+    await writeLock(scopeDir, lock);
+}
+/** An installed extension's options, as they are now. */
+export async function extensionOptionStates(installed) {
+    const declared = installed.manifest?.userConfig ?? {};
+    const values = await readOptionValues(installed.privateDir, installed.name, declared, installed.lock.options);
+    const secrets = await readOptionValues(installed.privateDir, installed.name, Object.fromEntries(Object.entries(declared).map(([key, option]) => [key, { ...option, default: undefined }])), installed.lock.options);
+    return Object.entries(declared).map(([key, option]) => {
+        const value = values[key];
+        const own = secrets[key];
+        return { key, option, ...(value !== undefined && !option.sensitive ? { value } : {}), set: value !== undefined && value !== "", isDefault: value !== undefined && own === undefined };
+    });
+}

package/dist/core/hooks/planGate.d.ts

@@ -9,6 +9,8 @@ export interface PlanScope {
     isReadOnlyTool?(toolName: string, input: Record<string, unknown>): boolean;
     /** The enabled extensions' MCP tools that only read (`mcp__<server>__<tool>`). */
     readOnlyTools?: readonly string[];
+    /** Whether an MCP tool's own server marks it `readOnlyHint`, for the extensions whose manifest lists none (readOnlyHints.ts). */
+    isReadOnlyHinted?(toolName: string): Promise<boolean>;
 }
 /**
  * The reason to deny `toolName` with `input` in plan mode, or `undefined` to let it through.

package/dist/core/hooks/planGate.js

@@ -41,6 +41,9 @@ export function createPlanGate(scope, isActive) {
         const reason = checkPlanScope(scope, pre.tool_name, (pre.tool_input ?? {}));
         if (!reason)
             return {};
+        // Asked last, and only for an MCP tool nothing else let through: it's a call to the session.
+        if (pre.tool_name.startsWith("mcp__") && (await scope.isReadOnlyHinted?.(pre.tool_name)))
+            return {};
         return {
             hookSpecificOutput: {
                 hookEventName: pre.hook_event_name,

package/dist/core/interaction.d.ts

@@ -1,3 +1,4 @@
+import type { FormAnswer, FormRequest } from "./elicitation.js";
 /** What a checkpoint shows the person: a title, detail lines and, in a plain terminal, the question. */
 export interface ApprovalPrompt {
     title: string;
@@ -43,6 +44,12 @@ export interface InteractionPort {
      * `askDecision()`, with the options numbered in the prompt.
      */
     askChoice?(prompt: ApprovalPrompt, choice: ChoiceSettings, signal: AbortSignal): Promise<string>;
+    /**
+     * A form an MCP server asks for (elicitation, #58), whole: its fields, and the person's
+     * values, or that they declined or cancelled. Optional: without it the kit asks field by
+     * field through the other methods. Never written to a log: the answer is the server's.
+     */
+    askForm?(form: FormRequest, signal: AbortSignal): Promise<FormAnswer>;
     /** A one-way message for the person. */
     notify(message: string): void;
 }

package/dist/core/liveExtensions.d.ts

@@ -5,23 +5,37 @@ import type { ToolLabels } from "./toolLabels.js";
  * Turning an installed extension off and on in a running session (#49), without reopening it.
  * Only one that was running when the session opened: its MCP servers are toggled
  * (`toggleMcpServer()`, which removes their tools from the model's context and brings them back,
- * confirmed empirically) and its plugin, a copy in the run's folder, is emptied or filled again
+ * confirmed empirically) and its plugin, mounted in the run's folder, is unmounted or mounted again
  * before `reloadPlugins()` (its skills, commands and subagents go and come back, confirmed
- * empirically). The kit's own lists follow: the plan gate's read-only tools, the subagent gates'
+ * empirically, through a link too). The kit's own lists follow: the plan gate's read-only tools, the subagent gates'
  * allowed types, the chat's labels, `/extensions` and what `about_me` says. One that wasn't
  * running has no plugin path the session knows: it takes reopening the session.
  *
  * Not through `setMcpServers()`: it leaves the servers given at start alone (confirmed
  * empirically: removing one from its set removes nothing).
  */
+/**
+ * Mounts an installed extension's plugin at `at`, in a run's folder, for the session to load from
+ * there: a link to it (a junction on Windows, which needs no privilege), so nothing is copied and
+ * its `node_modules` costs nothing; a copy where a link can't be made. The CLI loads a plugin
+ * through a link, and `reloadPlugins()` unloads it when the link goes and loads it when it's back
+ * (confirmed empirically).
+ */
+export declare function mountPlugin(from: string, at: string): Promise<"link" | "copy">;
+/**
+ * Takes a mounted plugin away: a link is removed, never what it points at (its contents are the
+ * installed extension); a copy is emptied, so the path stays for mounting it again.
+ */
+export declare function unmountPlugin(at: string): Promise<void>;
 /** What an installed extension brought to this session, to take it away and bring it back. */
 export interface LiveExtension {
     name: string;
-    /** Where it's installed (its scope's folder): the plugin copy is filled from there. */
+    /** Its plugin as installed (in its scope's folder, or where it's linked): what's mounted in the run's folder. */
     installedDir: string;
+    /** Its scope's folder, where its lock is. */
     scopeDir: string;
-    /** Its plugin, copied into the run's folder for this session. */
-    pluginCopy: string;
+    /** Where its plugin is mounted in the run's folder for this session (`mountPlugin()`). */
+    pluginMount: string;
     servers: string[];
     readOnlyTools: string[];
     toolLabels: ToolLabels;
@@ -49,3 +63,14 @@ export interface LiveTargets {
 export type ExtensionSwitch = (name: string, enabled: boolean) => Promise<boolean>;
 /** The switch for a session's installed extensions. */
 export declare function createExtensionSwitch(extensions: readonly LiveExtension[], targets: LiveTargets): ExtensionSwitch;
+/**
+ * Restarts `name`'s MCP servers in the running session, so they take its options as they are now
+ * (#55): the launcher reads them when it starts a server. `reconnectMcpServer()` ends a server's
+ * process and starts a new one with the session's config (confirmed empirically; `setMcpServers()`
+ * replaced every server of the session and left the old process running). False when it can't
+ * be done here (not running in this session, or the session hasn't started): the next session
+ * takes them.
+ */
+export type ExtensionRestart = (name: string) => Promise<boolean>;
+/** The restart for a session's installed extensions. */
+export declare function createExtensionRestart(extensions: readonly LiveExtension[], targets: LiveTargets): ExtensionRestart;