@falkenslab/agent-kit 0.21.0 → 0.22.0

package/dist/core/externalExtensions.js

@@ -9,6 +9,9 @@ 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
@@ -19,6 +22,39 @@ export const LOCK_FILE = "extensions.lock.json";
 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 {
@@ -48,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.
@@ -69,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.
@@ -113,26 +161,50 @@ 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, folders) {
+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`;
+        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})`;
-    // 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)]));
-    return { entry, args, env: { CLAUDE_PLUGIN_ROOT: root, CLAUDE_PLUGIN_DATA: folders.data, ...declared } };
+    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 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;
@@ -141,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) {
@@ -151,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("");
@@ -199,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 = lock.linked ? lock.source : 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, scopeDir, dir, dataDir: extensionDataDir(scopeDir, name), 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;
@@ -225,7 +320,7 @@ 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,
@@ -236,38 +331,73 @@ function externalExtension(installed, manifest) {
             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, { root: installed.dir, data: installed.dataDir });
+                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). */
@@ -283,9 +413,11 @@ export async function onPath(program, env = process.env) {
     }
     return false;
 }
-async function problem(installed) {
+async function problem(installed, cache) {
     let manifest;
     try {
+        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);
@@ -303,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. */
@@ -316,7 +451,9 @@ export function isGitSource(source) {
  * 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; its data folder stays. With `link`, a folder is registered where it is
- * instead, to develop it: not copied, and its files not checked.
+ * 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))
@@ -347,21 +484,41 @@ export async function addExtension(source, scopeDir, options = {}) {
         // 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: "", enabled: true, installed: new Date().toISOString() };
+            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(),
         };
@@ -378,13 +535,16 @@ export async function addExtension(source, scopeDir, options = {}) {
  * 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(scopeDir, name), { recursive: true, force: true });
+        await rm(extensionDataDir(privateDir, name), { recursive: true, force: true });
+    await removeSecrets(privateDir, name);
     await writeLock(scopeDir, lock);
     return true;
 }
@@ -409,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

@@ -63,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;

package/dist/core/liveExtensions.js

@@ -1,6 +1,7 @@
 import { cp, lstat, mkdir, readdir, rm, symlink, unlink } from "node:fs/promises";
 import path from "node:path";
 import { hashExtension, listInstalled, readLock } from "./externalExtensions.js";
+import { cachedPackagesIntact, packageCacheDir } from "./npxPackages.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
@@ -68,6 +69,9 @@ export function createExtensionSwitch(extensions, targets) {
             const lock = (await readLock(extension.scopeDir))[name];
             if (!lock || (!lock.linked && lock.sha256 !== (await hashExtension(extension.installedDir))))
                 return false;
+            // The packages its npx servers run (#54), checked whether it's linked or not.
+            if (!(await cachedPackagesIntact(packageCacheDir(targets.status.dirs), lock.packages)))
+                return false;
             await mountPlugin(extension.installedDir, extension.pluginMount);
         }
         else {
@@ -85,6 +89,24 @@ export function createExtensionSwitch(extensions, targets) {
         return true;
     };
 }
+/** The restart for a session's installed extensions. */
+export function createExtensionRestart(extensions, targets) {
+    return async (name) => {
+        const extension = extensions.find((candidate) => candidate.name === name);
+        const reconnect = targets.controls().reconnectMcpServer;
+        if (!extension || !reconnect || !extension.servers.length)
+            return false;
+        try {
+            for (const server of extension.servers)
+                await reconnect(server);
+            return true;
+        }
+        catch {
+            // Turned off in the session: it starts with them when it's turned on again.
+            return false;
+        }
+    };
+}
 /** The kit's lists, as the extension is now. */
 function follow(extension, enabled, targets) {
     const without = (list, items) => {

package/dist/core/marketplaces.d.ts

@@ -108,9 +108,13 @@ export type ResolvedSource = {
 export declare function resolvePluginSource(marketplace: KnownMarketplace, plugin: MarketplacePlugin): ResolvedSource;
 /**
  * Installs `<plugin>@<marketplace>` (or a plugin only one known marketplace offers) into a scope,
- * locked with where it came from. Its name in the agent is its `plugin.json`'s, as for any extension.
+ * locked with where it came from (the packages its npx servers run into `options.packages`, #54).
+ * Its name in the agent is its `plugin.json`'s, as for any extension.
  */
-export declare function installFromMarketplace(dir: string, spec: string, scopeDir: string): Promise<{
+export declare function installFromMarketplace(dir: string, spec: string, scopeDir: string, options?: {
+    packages?: string;
+    store?: string;
+}): Promise<{
     name: string;
     replaced: boolean;
     commit?: string;

package/dist/core/marketplaces.js

@@ -208,9 +208,10 @@ export function resolvePluginSource(marketplace, plugin) {
 }
 /**
  * Installs `<plugin>@<marketplace>` (or a plugin only one known marketplace offers) into a scope,
- * locked with where it came from. Its name in the agent is its `plugin.json`'s, as for any extension.
+ * locked with where it came from (the packages its npx servers run into `options.packages`, #54).
+ * Its name in the agent is its `plugin.json`'s, as for any extension.
  */
-export async function installFromMarketplace(dir, spec, scopeDir) {
+export async function installFromMarketplace(dir, spec, scopeDir, options = {}) {
     const { marketplace, plugin } = await findPlugin(dir, spec);
     const resolved = resolvePluginSource(marketplace, plugin);
     const from = `${plugin.name}@${marketplace.name}`;
@@ -218,7 +219,7 @@ export async function installFromMarketplace(dir, spec, scopeDir) {
         const { name, version, registry } = resolved.npm;
         const fetched = await fetchNpmPlugin(name, version, registry);
         try {
-            return { ...(await addExtension(fetched.dir, scopeDir, { marketplace: from, origin: `npm:${name}@${fetched.version}` })), marketplace: marketplace.name };
+            return { ...(await addExtension(fetched.dir, scopeDir, { ...options, marketplace: from, origin: `npm:${name}@${fetched.version}` })), marketplace: marketplace.name };
         }
         finally {
             await rm(fetched.dir, { recursive: true, force: true });
@@ -227,13 +228,14 @@ export async function installFromMarketplace(dir, spec, scopeDir) {
     if ("archive" in resolved) {
         const fetched = await fetchArchivePlugin(resolved.archive.url, resolved.archive.sha256);
         try {
-            return { ...(await addExtension(fetched.root, scopeDir, { marketplace: from, origin: resolved.archive.url })), marketplace: marketplace.name };
+            return { ...(await addExtension(fetched.root, scopeDir, { ...options, marketplace: from, origin: resolved.archive.url })), marketplace: marketplace.name };
         }
         finally {
             await rm(fetched.dir, { recursive: true, force: true });
         }
     }
     const result = await addExtension(resolved.source, scopeDir, {
+        ...options,
         ...(resolved.subdir ? { subdir: resolved.subdir } : {}),
         ...(resolved.sha ? { sha: resolved.sha } : {}),
         marketplace: from,

package/dist/core/messages/de.js

@@ -32,8 +32,40 @@ export const de = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "aktiviert" : "deaktiviert"}, in derselben Sitzung)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "aktiviert" : "deaktiviert"}: die Sitzung wird mit derselben Unterhaltung neu geöffnet)`,
     extensionNotInstalled: (name) => `(${name} ist nicht installiert: /extensions listet sie auf)`,
-    extensionsUsage: "(Verwendung: /extensions, /extensions enable <Name>, /extensions disable <Name>)",
+    extensionsUsage: "(Verwendung: /extensions, enable|disable <Name>, config <Name> [Schlüssel=Wert…], search [Wörter], install <Name>, update [Name], remove <Name> [--delete-data], reload, trust)",
     extensionsCantReopen: "(dieser Chat kann seine Sitzung nicht neu öffnen: im Terminal aktivieren oder deaktivieren und neu starten)",
+    extensionOptions: (name) => `Optionen von ${name}:`,
+    extensionNoOptions: (name) => `(${name} hat keine Optionen)`,
+    optionNotSet: "(nicht gesetzt)",
+    optionSecretSet: "(gesetzt, verborgen)",
+    optionDefault: "(Standard)",
+    optionRequired: "erforderlich",
+    optionSensitiveInChat: (key, name) => `(${key} ist ein Geheimnis: was im Chat getippt wird, bleibt in seinem Verlauf, also im Terminal setzen: extension config ${name} ${key})`,
+    extensionOptionsSaved: (name) => `(Optionen von ${name} gespeichert: sie gelten, wenn sein Server neu startet)`,
+    extensionRestarted: (name) => `(Optionen von ${name} gespeichert, und sein Server damit neu gestartet, in derselben Sitzung)`,
+    extensionReconfiguredReopen: (name) => `(Optionen von ${name} gespeichert: die Sitzung wird neu geöffnet, mit demselben Gespräch)`,
+    extensionsNoMatch: "(keine Erweiterung passt: /extensions search mit anderen Wörtern, oder ohne, um alle zu sehen)",
+    extensionIsInstalled: "(installiert)",
+    extensionUpdateAvailable: (installed) => `(installiert: ${installed}, Update verfügbar)`,
+    extensionInstalled: (name) => `(${name} installiert: in einem neuen Gespräch da, oder sofort mit /extensions reload, ohne dieses zu verlieren)`,
+    extensionUpdated: (name, from, to) => `(${name} aktualisiert, ${from} → ${to}: in einem neuen Gespräch da, oder sofort mit /extensions reload)`,
+    extensionsUpToDate: "(alle Erweiterungen aus einem Marketplace sind aktuell)",
+    extensionRemoved: (name, withData) => `(${name} deinstalliert${withData ? ", mit seinen Daten" : "; seine Daten bleiben für eine Neuinstallation"})`,
+    extensionConfirm: (spec, marketplace) => `(${spec} kommt aus ${marketplace}, nicht aus dem Marketplace dieses Agenten: es liefe auf diesem Computer mit deinen Rechten. /extensions install ${spec} --yes installiert es)`,
+    extensionsBusy: "(nach diesem Zug: der Agent arbeitet)",
+    extensionsReloaded: "(die Sitzung wird mit den jetzt installierten Erweiterungen neu geöffnet, mit demselben Gespräch)",
+    elicitTitle: (server) => `${server} fragt dich`,
+    elicitQuestion: "Antworten? (Enter/y: antworten, n: ablehnen, q: abbrechen) ",
+    elicitAgain: "Das ist kein gültiger Wert: versuch es nochmal, oder lass es leer.",
+    elicitNotANumber: (text) => `„${text}“ ist keine Zahl`,
+    elicitOutOfRange: (minimum, maximum) => `zwischen ${minimum ?? "…"} und ${maximum ?? "…"}`,
+    elicitUrlTitle: (server) => `${server} bittet dich, eine Seite zu öffnen`,
+    elicitUrlQuestion: "Öffne sie selbst, dann Enter, wenn du fertig bist (n: ablehnen) ",
+    trustTitle: "Dieser Arbeitsbereich bringt Erweiterungen mit",
+    trustBody: "Sie führen Code auf diesem Computer mit deinen Rechten aus. Vertraue ihnen nur, wenn du der Herkunft dieses Arbeitsbereichs vertraust:",
+    trustQuestion: "Ihnen vertrauen und sie ausführen? (y/N) ",
+    trustDeclined: "(sie bleiben aus: /extensions trust vertraut ihnen später)",
+    trustGiven: (names) => `(${names}: in diesem Arbeitsbereich vertraut, so wie sie sind; eine andere Version fragt erneut)`,
     currentRun: "(dieses)",
     resumed: (date) => `(Gespräch vom ${date} fortgesetzt)`,
     suggestionKey: "Tab",