@falkenslab/agent-kit 0.19.0 → 0.21.0

package/dist/core/session.js

@@ -22,6 +22,7 @@ import { replyLanguageInstruction } from "./language.js";
 import { chooseLanguage } from "./messages/index.js";
 import { createRunStore } from "./runs.js";
 import { createSessionView, registerSessionView } from "./sessionFacts.js";
+import { createExtensionSwitch, mountPlugin } from "./liveExtensions.js";
 import { agentKitVersion } from "./version.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
@@ -69,32 +70,39 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         runDir,
         mode,
         interactive: mode !== "autonomous",
+        // What the active ones provide, once they're resolved below.
+        capabilities: new Set(),
         session: () => (late.view ? late.view.facts() : Promise.reject(new Error("The session isn't built yet: call session() from a tool, not from contribute()."))),
     };
     // The installed ones (#37), the project's over the agent's: those that can't load are off with
     // why, and so is one named like an extension the spec enables.
     const extensionDirs = config.extensionDirs ?? {};
     const external = await loadExternalExtensions(extensionDirs);
-    const enabledNames = new Set((spec.extensions ?? []).map((entry) => (typeof entry === "string" ? entry : entry.name)));
+    const enabledNames = new Set((spec.extensions ?? []).map((extension) => extension.name));
     const resolved = resolveExtensions([...(spec.extensions ?? []), ...external.extensions.filter((extension) => !enabledNames.has(extension.name))], extensionContext);
     resolved.inactive.push(...external.off, ...external.extensions.filter((extension) => enabledNames.has(extension.name)).map((extension) => ({ name: extension.name, reason: "has the name of one this agent already has" })));
+    // Each installed one's plugin, mounted in the run's folder (a link, nothing copied): the running
+    // session unmounts and mounts it to turn the extension off and on (liveExtensions.ts), never
+    // touching what's installed.
+    const installedDirs = new Map();
+    for (const { extension } of resolved.active.filter(({ extension }) => extension.external)) {
+        const mount = path.join(runDir, "extensions", extension.name);
+        await mountPlugin(extension.plugin, mount);
+        installedDirs.set(extension.name, { dir: extension.plugin, scopeDir: extension.installedIn ?? path.dirname(extension.plugin) });
+        extension.plugin = mount;
+    }
     const externalPlugins = new Set(resolved.active.filter(({ extension }) => extension.external).map(({ extension }) => path.resolve(extension.plugin)));
+    extensionContext.capabilities = resolved.capabilities;
     const added = await Promise.all(resolved.active.map(({ extension }) => extension.contribute(extensionContext)));
     const extensionPlugins = resolved.active.map(({ extension }) => extension.plugin);
     const fromExtensions = (pick) => added.flatMap((contribution) => pick(contribution) ?? []);
-    const knowledgeStore = added.map((contribution) => contribution.api?.knowledgeStore).find(Boolean);
-    // An extension may claim `knowledgeDir` as reached only through its tools (the knowledge base,
-    // ADR-024); otherwise it's a folder of the agent's own notes, kept with the file tools under
-    // its own rules.
-    const claimed = (dir) => fromExtensions((contribution) => contribution.toolOnlyDirs).some((only) => path.resolve(only.dir) === path.resolve(dir));
-    const notesDir = config.knowledgeDir && !claimed(config.knowledgeDir) ? config.knowledgeDir : undefined;
     const extraDirs = config.extraWritableDirs ?? [];
     const readableExtras = config.extraReadableDirs ?? [];
-    // The file tools the session needs: all five for the notes and the extra writable folders,
-    // the reading ones for the extra readable folders, and whatever the extensions ask for (the
-    // sources' reading ones); without any of them, none.
+    // The file tools the session needs: all five for the extra writable folders, the reading ones
+    // for the extra readable folders, and whatever the extensions ask for (the sources' reading
+    // ones); without any of them, none.
     const wantedFileTools = new Set([
-        ...(notesDir || extraDirs.length ? FILE_TOOLS : []),
+        ...(extraDirs.length ? FILE_TOOLS : []),
         ...(readableExtras.length ? ["Read", "Glob", "Grep"] : []),
         ...fromExtensions((contribution) => contribution.fileTools),
     ]);
@@ -105,10 +113,10 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // searchable but deliberately NOT writable: the only way to add to them is its tools.
     const readOnlyDirs = fromExtensions((contribution) => contribution.readOnlyDirs);
     const toolOnlyDirs = fromExtensions((contribution) => contribution.toolOnlyDirs);
-    const writableDirs = [notesDir, ...extraDirs].filter((d) => Boolean(d));
-    const searchableDirs = [notesDir, ...readOnlyDirs, ...extraDirs, ...readableExtras].filter((d) => Boolean(d));
+    const writableDirs = extraDirs;
+    const searchableDirs = [...readOnlyDirs, ...extraDirs, ...readableExtras];
     // Skills/commands/plugins are a separate concern from the file tools: an agent that
-    // wants a plugin-provided skill/command but has no notes or sources folder shouldn't have
+    // wants a plugin-provided skill/command but has no folder of its own shouldn't have
     // to invent one just to get `cwd`/`skills: "all"`/`plugins` wired up. Gated on either
     // signal, not on `pluginRoots` alone, so an agent with file tools keeps getting the SDK's
     // own project-level `.claude/skills`/`.claude/commands` discovery.
@@ -160,6 +168,10 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // map, and inherits the full session tools (Bash included) rather than the narrow list
     // each declared subagent actually declares.
     const allowedSubagentTypes = [...new Set([...(subagents?.allowedSubagentTypes ?? []), ...Object.keys(fromPlugins)])];
+    // The extensions' read-only tools, for the plan gate: a list the live switch changes (liveExtensions.ts).
+    const readOnlyTools = fromExtensions((contribution) => contribution.readOnlyTools);
+    // What no file tool may touch: the agent's denied paths and the SDK's own credentials.
+    const deniedPaths = [...(config.deniedPaths ?? []), path.join(claudeConfigDir(), ".credentials.json")];
     const transcriptPath = path.join(runDir, "transcript.jsonl");
     const transcriptLogger = createTranscriptLogger(transcriptPath, config.secrets ?? []);
     const promptSections = [
@@ -195,6 +207,9 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             // An installed extension's plugin may carry hooks: none run (ADR-025). The kit's own,
             // passed in `hooks`, still do (confirmed empirically).
             ...(externalPlugins.size ? { disableAllHooks: true } : {}),
+            // The denied paths again, as the SDK's own rules: a second layer under the file scope gate,
+            // which a tool the gate doesn't know of can't pass either (#49).
+            permissions: { deny: denyRules(deniedPaths) },
         },
         // No built-in tools except, if applicable, Read/Write/Edit/Glob/Grep scoped to the
         // project's own folders (fileScopeGate below), and WebFetch/WebSearch
@@ -230,7 +245,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 // skills, on top of the plugin-provided built-ins from spec.pluginRoots()
                 // below. skipMcpDiscovery: true on those plugins is the caller's choice.
                 cwd: config.projectDir,
-                // Empty when there's no knowledgeDir/sourcesDir (the plugin-only case) — an
+                // Empty when there's no folder of the agent's or its extensions' (the plugin-only case) — an
                 // empty array is a valid, no-op value for this SDK option, not omitted, since
                 // this whole block is already conditioned on includeSkillsAndPlugins.
                 additionalDirectories: searchableDirs,
@@ -264,7 +279,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                                     searchableDirs,
                                     readOnlyDirs,
                                     // The SDK's own credentials, whatever the agent denies.
-                                    deniedPaths: [...(config.deniedPaths ?? []), path.join(claudeConfigDir(), ".credentials.json")],
+                                    deniedPaths,
                                     // Read and Glob only in the agent's folders, plus what only the kit knows it
                                     // needs: the run folder, the plugins, the project's .claude/ (when loaded) and
                                     // the SDK's large tool results. Never the rest of the disk (~/.ssh, other
@@ -287,7 +302,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                             hooks: [
                                 createPlanGate({
                                     projectDir: config.projectDir,
-                                    readOnlyTools: fromExtensions((contribution) => contribution.readOnlyTools),
+                                    readOnlyTools,
                                     ...(spec.planMode?.isPlanFile ? { isPlanFile: (filePath) => spec.planMode.isPlanFile(filePath, config) } : {}),
                                     ...(spec.planMode?.isReadOnlyTool ? { isReadOnlyTool: spec.planMode.isReadOnlyTool } : {}),
                                 }, () => modeControl.mode === "plan"),
@@ -321,7 +336,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         inactive: resolved.inactive,
     };
     // What the session is, for the extensions that ask (sessionFacts.ts, #43).
-    late.view = createSessionView({
+    const viewBase = {
         ...(spec.identity ? { identity: spec.identity } : {}),
         kitVersion: agentKitVersion(),
         language,
@@ -333,15 +348,39 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 servers: Object.keys(added[index]?.mcpServers ?? {}),
                 help: added[index]?.helpLines ?? [],
             })),
-            inactive: resolved.inactive,
+            // Its own list: /extensions' status has another, and the live switch changes both.
+            inactive: [...resolved.inactive],
         },
         subagents: Object.entries(allAgents).map(([name, agent]) => ({ name, description: agent.description })),
         skills: sdkOptions.skills === "all" ? await pluginSkills(pluginRoots) : [...(sdkOptions.skills ?? [])],
         runDir,
-    }, modeControl);
+    };
+    late.view = createSessionView(viewBase, modeControl);
     registerSessionView(sdkOptions, late.view);
+    // Turning an installed extension off and on while the session runs (#49).
+    const switchExtension = createExtensionSwitch(resolved.active.flatMap(({ extension, manifest }, index) => {
+        const installed = installedDirs.get(extension.name);
+        if (!installed)
+            return [];
+        const contribution = added[index];
+        return [
+            {
+                name: extension.name,
+                installedDir: installed.dir,
+                scopeDir: installed.scopeDir,
+                pluginMount: extension.plugin,
+                servers: Object.keys(contribution?.mcpServers ?? {}),
+                readOnlyTools: contribution?.readOnlyTools ?? [],
+                toolLabels: contribution?.toolLabels ?? {},
+                agents: Object.keys(fromPlugins).filter((agent) => agent.startsWith(`${extension.name}:`)),
+                description: manifest.description,
+                provides: manifest.provides,
+                help: contribution?.helpLines ?? [],
+            },
+        ];
+    }), { readOnlyTools, allowedSubagentTypes, toolLabels, status: extensions, facts: viewBase, controls: () => late.view?.controls() ?? {} });
     const apis = Object.fromEntries(resolved.active.flatMap(({ extension }, index) => (added[index]?.api ? [[extension.name, added[index].api]] : [])));
-    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, toolLabels, extensions, apis, ...(knowledgeStore ? { knowledgeStore } : {}) };
+    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, toolLabels, extensions, apis, switchExtension };
 }
 export { createModeControl, togglePlanMode } from "./modeControl.js";
 /** The Claude Code configuration folder the SDK's CLI uses: `CLAUDE_CONFIG_DIR`, or `~/.claude`. */
@@ -356,6 +395,19 @@ function claudeConfigDir() {
 export function claudeProjectDir(projectDir) {
     return path.join(claudeConfigDir(), "projects", path.resolve(projectDir).replace(/[^a-zA-Z0-9]/g, "-"));
 }
+/**
+ * The SDK's `permissions.deny` rules for paths no file tool may read or change, each one and
+ * whatever is inside it. An absolute path is written `//` and POSIX: `C:\Users\x` is
+ * `//c/Users/x` (confirmed empirically on Windows; on POSIX `/home/x` is `//home/x`). `Read`
+ * rules reach the tools that read, `Edit` rules those that write.
+ */
+export function denyRules(paths) {
+    return paths.flatMap((denied) => {
+        const posix = path.resolve(denied).replace(/\\/g, "/").replace(/^([A-Za-z]):/, (_, drive) => `/${drive.toLowerCase()}`);
+        const rule = `/${posix}`;
+        return [`Read(${rule})`, `Read(${rule}/**)`, `Edit(${rule})`, `Edit(${rule}/**)`];
+    });
+}
 /** The built-in file tools, in the order the session lists them. */
 const FILE_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep"];
 /**

package/dist/core/sessionFacts.d.ts

@@ -58,6 +58,9 @@ export interface SessionLive {
     skills?: string[];
     supportedCommands?: () => Promise<SlashCommand[]>;
     contextUsage?: () => Promise<ContextUsage | null>;
+    /** The running session's controls an installed extension is turned off and on with (liveExtensions.ts). */
+    toggleMcpServer?: (server: string, enabled: boolean) => Promise<void>;
+    reloadPlugins?: () => Promise<unknown>;
 }
 /** The facts known when the options are built: everything but the mode and what only the running session knows. */
 export type StaticSessionFacts = Omit<SessionFacts, "mode" | "switchableModes" | "tools" | "commands" | "context" | "extensions"> & {
@@ -71,6 +74,8 @@ export type StaticSessionFacts = Omit<SessionFacts, "mode" | "switchableModes" |
 export interface SessionView {
     facts(): Promise<SessionFacts>;
     attach(live: SessionLive): void;
+    /** What the running session has attached so far. */
+    controls(): SessionLive;
 }
 /** The view of a session: its static facts, the mode read from `modeControl` on every call, and what the running session attaches. */
 export declare function createSessionView(base: StaticSessionFacts, modeControl: ModeControl): SessionView;

package/dist/core/sessionFacts.js

@@ -8,6 +8,7 @@ export function createSessionView(base, modeControl) {
         attach(more) {
             live = { ...live, ...more };
         },
+        controls: () => live,
         async facts() {
             const tools = live.tools ?? [];
             const [commands, context] = await Promise.all([

package/dist/extensions/awareness/index.d.ts

@@ -4,10 +4,19 @@ import type { Extension } from "../../core/extensions.js";
 export declare function awarenessPluginRoot(): string;
 /** The "Who you are" section of the system prompt: name, version, what it is, the kit's version, and where to look. */
 export declare function identityPromptSection(identity: AgentIdentity): string;
+/** The awareness extension's options. */
+export interface AwarenessOptions {
+    /**
+     * Absolute path of a markdown guide to the agent's own domain (its commands, configuration,
+     * folders), which `about_me` gives the agent when the person asks.
+     */
+    guide?: string;
+}
 /**
  * The awareness (#43): the agent knows who it is and what it is at each moment of a session,
  * and the person can ask it. A "Who you are" section, `about_me` (the session's facts, read
- * anew on every call through `ExtensionContext.session()`, and the agent's `helpGuide`), and
- * the `help` skill, how the kit's chat is used, which doesn't change.
+ * anew on every call through `ExtensionContext.session()`, and the agent's `guide`), and
+ * the `help` skill, how the kit's chat is used, which doesn't change. It needs the spec's
+ * `identity`.
  */
-export declare const awarenessExtension: Extension;
+export declare function awareness(options?: AwarenessOptions): Extension;

package/dist/extensions/awareness/index.js

@@ -21,19 +21,22 @@ You are ${who}. You are built on agent-kit ${agentKitVersion()}, which provides
 /**
  * The awareness (#43): the agent knows who it is and what it is at each moment of a session,
  * and the person can ask it. A "Who you are" section, `about_me` (the session's facts, read
- * anew on every call through `ExtensionContext.session()`, and the agent's `helpGuide`), and
- * the `help` skill, how the kit's chat is used, which doesn't change.
+ * anew on every call through `ExtensionContext.session()`, and the agent's `guide`), and
+ * the `help` skill, how the kit's chat is used, which doesn't change. It needs the spec's
+ * `identity`.
  */
-export const awarenessExtension = {
-    name: "awareness",
-    plugin: awarenessPluginRoot(),
-    missing: ({ spec }) => (spec.identity ? undefined : "needs `identity` in the spec"),
-    async contribute({ spec, session }) {
-        return {
-            mcpServers: { awareness: createAwarenessServer(session, spec.helpGuide) },
-            promptSection: identityPromptSection(spec.identity),
-            readOnlyTools: ["mcp__awareness__about_me"],
-            toolLabels: awarenessToolLabels(),
-        };
-    },
-};
+export function awareness(options = {}) {
+    return {
+        name: "awareness",
+        plugin: awarenessPluginRoot(),
+        missing: ({ spec }) => (spec.identity ? undefined : "needs `identity` in the spec"),
+        async contribute({ spec, session }) {
+            return {
+                mcpServers: { awareness: createAwarenessServer(session, options.guide) },
+                promptSection: identityPromptSection(spec.identity),
+                readOnlyTools: ["mcp__awareness__about_me"],
+                toolLabels: awarenessToolLabels(),
+            };
+        },
+    };
+}

package/dist/extensions/awareness/tools.d.ts

@@ -2,4 +2,4 @@ import type { SessionFacts } from "../../core/sessionFacts.js";
 /** The session's facts as the model reads them: markdown, in English (ADR-019). */
 export declare function describeSession(facts: SessionFacts): string;
 /** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide. */
-export declare function createAwarenessServer(session: () => Promise<SessionFacts>, helpGuide?: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+export declare function createAwarenessServer(session: () => Promise<SessionFacts>, guide?: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/extensions/awareness/tools.js

@@ -41,12 +41,12 @@ export function describeSession(facts) {
     return sections.join("\n\n");
 }
 /** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide. */
-export function createAwarenessServer(session, helpGuide) {
+export function createAwarenessServer(session, guide) {
     const aboutMe = tool("about_me", "What you are right now: your mode and the ones the person can switch to, your extensions with their tools and the ones off (with why), your subagents, the commands the person can type, how full your context is. With `part: \"guide\"`, your own guide to your domain (your commands, configuration, folders). It changes during a session: call it whenever the person asks about you, rather than answering from memory.", { part: z.enum(["now", "guide"]).optional().describe("`now` (the default): what you are right now. `guide`: your own guide to your domain.") }, async ({ part }) => {
         if (part === "guide") {
-            if (!helpGuide)
+            if (!guide)
                 return ok("You have no guide of your own: for your domain, say only what your instructions tell you, and that the rest isn't documented.");
-            return ok(await readFile(helpGuide, "utf8"));
+            return ok(await readFile(guide, "utf8"));
         }
         return ok(describeSession(await session()));
     }, { annotations: { readOnlyHint: true } });

package/dist/extensions/knowledge/index.d.ts

@@ -1,8 +1,22 @@
-import type { Extension } from "../../core/extensions.js";
+import type { BaseSessionConfig } from "../../core/agentSpec.js";
+import { type Extension, type FolderOption } from "../../core/extensions.js";
+import type { KnowledgeStore, PageType } from "./knowledgeStore.js";
+/** The knowledge base's options. */
+export interface KnowledgeOptions<TConfig extends BaseSessionConfig = BaseSessionConfig> {
+    /** The knowledge base's folder, reached only through its tools, never the file tools. Without a folder the extension is off. */
+    dir: FolderOption<TConfig>;
+    /**
+     * The agent's own page types, besides the kit's (summary, concept, entity, synthesis,
+     * preference): each with its folder (`""` for the root), index section, description (told to
+     * the model) and template.
+     */
+    pageTypes?: PageType[];
+    /** Its store, instead of the kit's over markdown files in `dir` (e.g. a database or a vector store implementing `KnowledgeStore`). */
+    store?(config: TConfig, dir: string): KnowledgeStore;
+}
 /**
- * The built-in knowledge base (`config.knowledgeDir`, ADR-008, ADR-024): an interlinked wiki the
- * agent keeps only through its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over
- * markdown files, or the agent's own). Not enabled, `knowledgeDir` is left to the core as a
- * folder of the agent's own notes.
+ * The built-in knowledge base (ADR-008, ADR-024): an interlinked wiki the agent keeps only through
+ * its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over markdown files, or the agent's
+ * own). The host reads it through `apis.knowledge.knowledgeStore`.
  */
-export declare const knowledgeExtension: Extension;
+export declare function knowledge<TConfig extends BaseSessionConfig = BaseSessionConfig>(options: KnowledgeOptions<TConfig>): Extension;

package/dist/extensions/knowledge/index.js

@@ -1,35 +1,38 @@
+import { folderOf } from "../../core/extensions.js";
 import { createFileKnowledgeStore } from "./fileKnowledgeStore.js";
 import { knowledgeToolLabels } from "./labels.js";
 import { knowledgePluginRoot, knowledgePromptSection } from "./prompt.js";
 import { createKnowledgeServer } from "./tools.js";
 /**
- * The built-in knowledge base (`config.knowledgeDir`, ADR-008, ADR-024): an interlinked wiki the
- * agent keeps only through its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over
- * markdown files, or the agent's own). Not enabled, `knowledgeDir` is left to the core as a
- * folder of the agent's own notes.
+ * The built-in knowledge base (ADR-008, ADR-024): an interlinked wiki the agent keeps only through
+ * its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over markdown files, or the agent's
+ * own). The host reads it through `apis.knowledge.knowledgeStore`.
  */
-export const knowledgeExtension = {
-    name: "knowledge",
-    plugin: knowledgePluginRoot(),
-    missing: ({ config }) => (config.knowledgeDir ? undefined : "needs `knowledgeDir` in the config"),
-    async contribute({ config, spec, runDir, interactive }) {
-        const knowledgeDir = config.knowledgeDir;
-        const store = spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(knowledgeDir, { pageTypes: spec.knowledgePageTypes });
-        // The person's preferences, by title, for its prompt section (#33).
-        const preferences = (await store.list()).filter((page) => page.type === "preference" && page.status === "active").map(({ id, title }) => ({ id, title }));
-        return {
-            // knowledge_retire asks a person, so it exists only where there is one.
-            mcpServers: { knowledge: createKnowledgeServer(store, { runDir, interactive }) },
-            promptSection: knowledgePromptSection({ withSources: Boolean(config.sourcesDir), pageTypes: store.types(), preferences }),
-            // Never the file tools on the knowledge folder (ADR-024): the denial points to the tools.
-            toolOnlyDirs: [{ dir: knowledgeDir, instead: "the knowledge_* tools" }],
-            readOnlyTools: ["mcp__knowledge__knowledge_index", "mcp__knowledge__knowledge_search", "mcp__knowledge__knowledge_read", "mcp__knowledge__knowledge_check"],
-            selfAskingTools: ["mcp__knowledge__knowledge_retire"],
-            toolLabels: knowledgeToolLabels(),
-            helpLines: [
-                "You keep a knowledge base (your memory across sessions). Its commands: `/knowledge:ingest` (learn the new or changed files of the sources folder), `/knowledge:query <question>` (answer from it), `/knowledge:lint` (check it and fix what's mechanical).",
-            ],
-            api: { knowledgeStore: store },
-        };
-    },
-};
+export function knowledge(options) {
+    return {
+        name: "knowledge",
+        plugin: knowledgePluginRoot(),
+        missing: ({ config }) => (folderOf(options.dir, config) ? undefined : "needs a folder (`dir`)"),
+        async contribute({ config, runDir, interactive, capabilities }) {
+            const knowledgeDir = folderOf(options.dir, config);
+            const store = options.store?.(config, knowledgeDir) ?? createFileKnowledgeStore(knowledgeDir, { pageTypes: options.pageTypes });
+            // The person's preferences, by title, for its prompt section (#33).
+            const preferences = (await store.list()).filter((page) => page.type === "preference" && page.status === "active").map(({ id, title }) => ({ id, title }));
+            return {
+                // knowledge_retire asks a person, so it exists only where there is one.
+                mcpServers: { knowledge: createKnowledgeServer(store, { runDir, interactive }) },
+                // Beside the sources, its summaries say which original they're about.
+                promptSection: knowledgePromptSection({ withSources: capabilities.has("sources"), pageTypes: store.types(), preferences }),
+                // Never the file tools on the knowledge folder (ADR-024): the denial points to the tools.
+                toolOnlyDirs: [{ dir: knowledgeDir, instead: "the knowledge_* tools" }],
+                readOnlyTools: ["mcp__knowledge__knowledge_index", "mcp__knowledge__knowledge_search", "mcp__knowledge__knowledge_read", "mcp__knowledge__knowledge_check"],
+                selfAskingTools: ["mcp__knowledge__knowledge_retire"],
+                toolLabels: knowledgeToolLabels(),
+                helpLines: [
+                    "You keep a knowledge base (your memory across sessions). Its commands: `/knowledge:ingest` (learn the new or changed files of the sources folder), `/knowledge:query <question>` (answer from it), `/knowledge:lint` (check it and fix what's mechanical).",
+                ],
+                api: { knowledgeStore: store },
+            };
+        },
+    };
+}

package/dist/extensions/knowledge/knowledgeStore.d.ts

@@ -5,7 +5,7 @@
  * skills. A page is identified by its type and slug, `concept/bowline`, and links between
  * pages use that id too: `[Bowline](concept/bowline)`.
  */
-/** A kind of page: one of the kit's, or one an agent declares (`AgentSpec.knowledgePageTypes`). */
+/** A kind of page: one of the kit's, or one an agent declares (`knowledge({ pageTypes })`). */
 export interface PageType {
     /** Its name, lowercase: `concept`, `topic`. Page ids start with it. */
     type: string;

package/dist/extensions/knowledge/prompt.d.ts

@@ -1,11 +1,11 @@
 import type { PageType } from "./knowledgeStore.js";
 /**
- * The built-in knowledge base (an "LLM wiki"): `sourcesDir` holds the originals, `knowledgeDir`
- * is the wiki the agent maintains through the `knowledge_*` tools (ADR-024), and the rules below
+ * The built-in knowledge base (an "LLM wiki"): the sources folder holds the originals, its own
+ * folder is the wiki the agent maintains through the `knowledge_*` tools (ADR-024), and the rules below
  * plus the plugin's skills (knowledge-ingest, knowledge-query, knowledge-lint) and commands
  * (/knowledge:ingest, /knowledge:query, /knowledge:lint) are the schema that tells it how.
- * Domain-agnostic on purpose: an agent adds its own page types (`AgentSpec.knowledgePageTypes`),
- * or leaves it out of `AgentSpec.extensions` and writes its own rules for `knowledgeDir`.
+ * Domain-agnostic on purpose: an agent adds its own page types (`knowledge({ pageTypes })`), or
+ * leaves it out of `AgentSpec.extensions` and keeps notes of its own in `extraWritableDirs`.
  */
 /** Absolute path of the knowledge base's plugin shipped with the kit, next to `dist/` (or `src/` under tsx). */
 export declare function knowledgePluginRoot(): string;

package/dist/extensions/knowledge/prompt.js

@@ -1,12 +1,12 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 /**
- * The built-in knowledge base (an "LLM wiki"): `sourcesDir` holds the originals, `knowledgeDir`
- * is the wiki the agent maintains through the `knowledge_*` tools (ADR-024), and the rules below
+ * The built-in knowledge base (an "LLM wiki"): the sources folder holds the originals, its own
+ * folder is the wiki the agent maintains through the `knowledge_*` tools (ADR-024), and the rules below
  * plus the plugin's skills (knowledge-ingest, knowledge-query, knowledge-lint) and commands
  * (/knowledge:ingest, /knowledge:query, /knowledge:lint) are the schema that tells it how.
- * Domain-agnostic on purpose: an agent adds its own page types (`AgentSpec.knowledgePageTypes`),
- * or leaves it out of `AgentSpec.extensions` and writes its own rules for `knowledgeDir`.
+ * Domain-agnostic on purpose: an agent adds its own page types (`knowledge({ pageTypes })`), or
+ * leaves it out of `AgentSpec.extensions` and keeps notes of its own in `extraWritableDirs`.
  */
 /** Absolute path of the knowledge base's plugin shipped with the kit, next to `dist/` (or `src/` under tsx). */
 export function knowledgePluginRoot() {

package/dist/extensions/memory/index.d.ts

@@ -1,12 +1,21 @@
-import type { Extension } from "../../core/extensions.js";
+import type { BaseSessionConfig } from "../../core/agentSpec.js";
+import { type Extension, type FolderOption } from "../../core/extensions.js";
 /** Absolute path of the memory extension's plugin, next to `dist/` (or `src/` under tsx). */
 export declare function memoryPluginRoot(): string;
 /** The memory's section of the system prompt: what it is, what it holds now, and its rules. */
 export declare function memoryPromptSection(index: string): string;
+/** The memory's options. */
+export interface MemoryOptions<TConfig extends BaseSessionConfig = BaseSessionConfig> {
+    /**
+     * Its folder, the agent's own outside any project (e.g. `~/.miyagi/memory`), kept across all
+     * the person's projects and never shared with another agent. Without a folder the extension is off.
+     */
+    dir: FolderOption<TConfig>;
+}
 /**
- * The memory of the person (`config.memoryDir`, #34): what the agent learns about the person it
- * works for, kept across all their projects in a folder of its own, reached only through its
- * tools (`recall`, `remember`, `forget`). What it remembers must quote the person's own messages, which it hears through
- * a `UserPromptSubmit` hook (and, for a resumed run, from the run's conversation).
+ * The memory of the person (#34): what the agent learns about the person it works for, kept
+ * across all their projects in a folder of its own, reached only through its tools (`recall`,
+ * `remember`, `forget`). What it remembers must quote the person's own messages, which it hears
+ * through a `UserPromptSubmit` hook (and, for a resumed run, from the run's conversation).
  */
-export declare const memoryExtension: Extension;
+export declare function memory<TConfig extends BaseSessionConfig = BaseSessionConfig>(options: MemoryOptions<TConfig>): Extension;

package/dist/extensions/memory/index.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { folderOf } from "../../core/extensions.js";
 import { readConversation } from "../../core/runs.js";
 import { memoryToolLabels } from "./labels.js";
 import { createMemoryStore } from "./memoryStore.js";
@@ -22,35 +23,37 @@ ${index}
 - Write entries in the language you reply in.`;
 }
 /**
- * The memory of the person (`config.memoryDir`, #34): what the agent learns about the person it
- * works for, kept across all their projects in a folder of its own, reached only through its
- * tools (`recall`, `remember`, `forget`). What it remembers must quote the person's own messages, which it hears through
- * a `UserPromptSubmit` hook (and, for a resumed run, from the run's conversation).
+ * The memory of the person (#34): what the agent learns about the person it works for, kept
+ * across all their projects in a folder of its own, reached only through its tools (`recall`,
+ * `remember`, `forget`). What it remembers must quote the person's own messages, which it hears
+ * through a `UserPromptSubmit` hook (and, for a resumed run, from the run's conversation).
  */
-export const memoryExtension = {
-    name: "memory",
-    plugin: memoryPluginRoot(),
-    missing: ({ config }) => (config.memoryDir ? undefined : "needs `memoryDir` in the config"),
-    async contribute({ config, runDir }) {
-        const memoryDir = config.memoryDir;
-        const store = createMemoryStore(memoryDir);
-        // What the person wrote: earlier in a resumed run, then each message as it's sent.
-        const said = (await readConversation(runDir)).filter((message) => message.role === "user").map((message) => message.text);
-        const hear = async (input) => {
-            if (input.hook_event_name === "UserPromptSubmit")
-                said.push(input.prompt);
-            return {};
-        };
-        return {
-            mcpServers: { memory: createMemoryServer(store, said) },
-            promptSection: memoryPromptSection(memoryIndex(await store.list())),
-            toolOnlyDirs: [{ dir: memoryDir, instead: "its tools: recall, remember, forget" }],
-            readOnlyTools: ["mcp__memory__recall"],
-            hooks: { UserPromptSubmit: [{ hooks: [hear] }] },
-            toolLabels: memoryToolLabels(),
-            helpLines: [
-                "You keep a memory of the person across all their projects (how they like things done, who they are): `/memory:list` shows it, `/memory:forget <entry>` forgets an entry. Only what they tell you goes in it.",
-            ],
-        };
-    },
-};
+export function memory(options) {
+    return {
+        name: "memory",
+        plugin: memoryPluginRoot(),
+        missing: ({ config }) => (folderOf(options.dir, config) ? undefined : "needs a folder (`dir`)"),
+        async contribute({ config, runDir }) {
+            const memoryDir = folderOf(options.dir, config);
+            const store = createMemoryStore(memoryDir);
+            // What the person wrote: earlier in a resumed run, then each message as it's sent.
+            const said = (await readConversation(runDir)).filter((message) => message.role === "user").map((message) => message.text);
+            const hear = async (input) => {
+                if (input.hook_event_name === "UserPromptSubmit")
+                    said.push(input.prompt);
+                return {};
+            };
+            return {
+                mcpServers: { memory: createMemoryServer(store, said) },
+                promptSection: memoryPromptSection(memoryIndex(await store.list())),
+                toolOnlyDirs: [{ dir: memoryDir, instead: "its tools: recall, remember, forget" }],
+                readOnlyTools: ["mcp__memory__recall"],
+                hooks: { UserPromptSubmit: [{ hooks: [hear] }] },
+                toolLabels: memoryToolLabels(),
+                helpLines: [
+                    "You keep a memory of the person across all their projects (how they like things done, who they are): `/memory:list` shows it, `/memory:forget <entry>` forgets an entry. Only what they tell you goes in it.",
+                ],
+            };
+        },
+    };
+}

package/dist/extensions/sources/index.d.ts

@@ -1,9 +1,21 @@
-import type { Extension } from "../../core/extensions.js";
+import type { BaseSessionConfig } from "../../core/agentSpec.js";
+import { type Extension, type FolderOption } from "../../core/extensions.js";
 /** Absolute path of the sources extension's plugin, next to `dist/` (or `src/` under tsx). */
 export declare function sourcesPluginRoot(): string;
+/** The sources extension's options. */
+export interface SourcesOptions<TConfig extends BaseSessionConfig = BaseSessionConfig> {
+    /**
+     * The sources folder: original files kept as obtained, apart from any notes. Material the
+     * person drops in, plus whatever the agent saves with `save_to_sources` (downloaded documents,
+     * transcripts…). The agent reads and searches it, never edits it, and `save_to_sources` never
+     * overwrites. Without a folder the extension is off.
+     */
+    dir: FolderOption<TConfig>;
+    /** The `save_to_sources` tool's description in the agent's own words, instead of the kit's generic one. */
+    saveDescription?: string;
+}
 /**
- * The sources folder (`config.sourcesDir`): originals kept as obtained, read with `Read` and
- * `extract_text`, added and retired only through its tools (`sourceFiles`). It knows nothing of
- * a knowledge base (#30).
+ * The sources folder: originals kept as obtained, read with `Read` and `extract_text`, added and
+ * retired only through its tools (`sourceFiles`). It knows nothing of a knowledge base (#30).
  */
-export declare const sourcesExtension: Extension;
+export declare function sources<TConfig extends BaseSessionConfig = BaseSessionConfig>(options: SourcesOptions<TConfig>): Extension;