@falkenslab/agent-kit 0.18.0 → 0.20.0

package/dist/core/session.js

@@ -1,4 +1,4 @@
-import { readdir, readFile } from "node:fs/promises";
+import { cp, readdir, readFile, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { createTranscriptLogger } from "./hooks/transcriptLogger.js";
@@ -10,18 +10,20 @@ import { createFileScopeGate } from "./hooks/fileScopeGate.js";
 import { createPlanGate } from "./hooks/planGate.js";
 import { createHumanApprovalServer } from "./tools/humanApproval.js";
 import { createManualLoginServer } from "./tools/manualLogin.js";
-import { createSaveToSourcesServer, sourcesPromptSection } from "./tools/saveToSources.js";
 import { createTimeServer } from "./tools/time.js";
 import { TODO_TOOL } from "./todos.js";
 import { createModeControl } from "./modeControl.js";
-import { createFileKnowledgeStore } from "./fileKnowledgeStore.js";
-import { createKnowledgeServer } from "./tools/knowledgeTools.js";
+import { extensionsPromptSection, resolveExtensions, skillsMissingCapabilities } from "./extensions.js";
 import { allowAnyMcpTool } from "./mcpPermissions.js";
-import { knowledgePluginRoot, knowledgePromptSection } from "./knowledge.js";
-import { AGENT_HELP_SKILL, identityPromptSection, writeAgentHelpPlugin } from "./agentHelp.js";
+import { pluginAgents } from "./pluginAgents.js";
+import { outsideArchive, unpackedClaudeExecutable } from "./packaged.js";
+import { listInstalled, loadExternalExtensions } from "./externalExtensions.js";
 import { replyLanguageInstruction } from "./language.js";
 import { chooseLanguage } from "./messages/index.js";
 import { createRunStore } from "./runs.js";
+import { createSessionView, registerSessionView } from "./sessionFacts.js";
+import { createExtensionSwitch } from "./liveExtensions.js";
+import { agentKitVersion } from "./version.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
  * *how* the agent runs a session (system prompt, tools, MCP servers, hooks), independent
@@ -29,9 +31,10 @@ import { createRunStore } from "./runs.js";
  * one-shot run or an `AsyncIterable` for a multi-turn chat).
  *
  * Everything actually *about the domain* (which system prompt, which MCP servers besides
- * the generic human-in-the-loop/knowledge ones below, which plugin roots, which
- * subagents) is behind `spec` (see agentSpec.ts) — this function only knows the generic
- * fields on `BaseSessionConfig`.
+ * the generic human-in-the-loop ones below, which plugin roots, which subagents) is behind
+ * `spec` (see agentSpec.ts), and the kit's optional parts (the knowledge base, the sources
+ * folder) are extensions whose contributions this function puts together (extensions.ts,
+ * ADR-025): it names none of them.
  *
  * The per-mode behavioral differences (whether the approval/manual-intervention tools
  * exist, whether the interactive step gate or the plan gate decides) all fall out of
@@ -57,60 +60,78 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // domain's own opt-in signal (see its doc comment in agentSpec.ts), not a generic
     // boolean this kit could infer on its own.
     const manualInterventionTexts = mode !== "autonomous" ? spec.manualInterventionTexts : undefined;
-    // The file tools exist as soon as the project has a place for the agent's notes
-    // (`knowledgeDir`) or for original files (`sourcesDir`) — there is no separate "context"
-    // folder: material the user provides is just more of `sourcesDir`.
-    const includeFileTools = Boolean(config.knowledgeDir || config.sourcesDir);
-    // The built-in knowledge base (rules in the system prompt + its skills/commands as a plugin) needs
-    // somewhere to keep the wiki, so it follows `knowledgeDir`; `spec.knowledgeBase: false` opts out.
-    const includeKnowledgeBase = Boolean(config.knowledgeDir) && spec.knowledgeBase !== false;
-    // The agent reaches it only through the `knowledge_*` tools, over a store, never with the file
-    // tools (ADR-024). Without it (`knowledgeBase: false`), `knowledgeDir` is a folder of the
-    // agent's own notes, kept with the file tools under its own rules.
-    const notesDir = includeKnowledgeBase ? undefined : config.knowledgeDir;
+    // What the enabled extensions bring (ADR-025): their tools, prompt sections, plugins and
+    // folders, put together here.
+    // `session()` reads the view built below, once the options are: an extension's tools call it later.
+    const late = {};
+    const extensionContext = {
+        config,
+        spec,
+        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((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, copied into the run's folder: the running session empties and
+    // fills the copy to turn the extension off and on (liveExtensions.ts), never what's installed.
+    const installedDirs = new Map();
+    for (const { extension } of resolved.active.filter(({ extension }) => extension.external)) {
+        const copy = path.join(runDir, "extensions", extension.name);
+        await rm(copy, { recursive: true, force: true });
+        await cp(extension.plugin, copy, { recursive: true });
+        installedDirs.set(extension.name, extension.plugin);
+        extension.plugin = copy;
+    }
+    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 extraDirs = config.extraWritableDirs ?? [];
     const readableExtras = config.extraReadableDirs ?? [];
-    // With the knowledge base, the file tools are only for the originals (reading) and the extra
-    // folders; without either, none.
-    const fileTools = !includeFileTools
-        ? []
-        : !includeKnowledgeBase
-            ? ["Read", "Write", "Edit", "Glob", "Grep"]
-            : [...(config.sourcesDir || extraDirs.length || readableExtras.length ? ["Read", "Glob", "Grep"] : []), ...(extraDirs.length ? ["Write", "Edit"] : [])];
+    // 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([
+        ...(extraDirs.length ? FILE_TOOLS : []),
+        ...(readableExtras.length ? ["Read", "Glob", "Grep"] : []),
+        ...fromExtensions((contribution) => contribution.fileTools),
+    ]);
+    const fileTools = FILE_TOOLS.filter((tool) => wantedFileTools.has(tool));
     // Where Write/Edit may act and Grep may search (see hooks/fileScopeGate.ts): the
     // project's own folders, never the whole cwd — which would include whatever else the
-    // project directory holds (the user's config...). `sourcesDir` is searchable but
-    // deliberately NOT writable: originals stay as obtained, and the only way to add to it is
-    // the `save_to_sources` tool (which never overwrites).
-    const writableDirs = [notesDir, ...extraDirs].filter((d) => Boolean(d));
-    const searchableDirs = [notesDir, config.sourcesDir, ...extraDirs, ...readableExtras].filter((d) => Boolean(d));
-    const readOnlyDirs = config.sourcesDir ? [config.sourcesDir] : [];
+    // project directory holds (the user's config...). An extension's folders (the sources) are
+    // 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 = 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.
-    // With an identity, the agent-help skill (agentHelp.ts): written into the run's folder, since
-    // it carries this session's facts and the agent's own guide.
-    const helpPlugin = spec.identity
-        ? await writeAgentHelpPlugin(path.join(runDir, "agent-help"), {
-            mode,
-            switchable: modeControl.switchable,
-            knowledgeBase: includeKnowledgeBase,
-            ...(config.sourcesDir ? { sourcesFolder: `${path.relative(config.projectDir, config.sourcesDir).split(path.sep).join("/")}/` } : {}),
-        }, spec.helpGuide)
-        : undefined;
-    const pluginRoots = [
-        ...spec.pluginRoots(config),
-        ...(includeKnowledgeBase ? [knowledgePluginRoot()] : []),
-        ...(helpPlugin ? [helpPlugin] : []),
-    ];
-    const knowledgeStore = includeKnowledgeBase && config.knowledgeDir
-        ? (spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(config.knowledgeDir, { pageTypes: spec.knowledgePageTypes }))
-        : undefined;
-    const includeSkillsAndPlugins = includeFileTools || pluginRoots.length > 0;
-    // "plugins": the skills of the plugins loaded, named as the SDK names them.
-    const offeredSkills = spec.skills === "plugins" ? await pluginSkills(pluginRoots) : spec.skills;
+    // Outside the archive when the agent runs packaged (Electron's app.asar): the CLI reads them (#42).
+    const pluginRoots = [...spec.pluginRoots(config), ...extensionPlugins].map(outsideArchive);
+    const includeSkillsAndPlugins = fileTools.length > 0 || pluginRoots.length > 0;
+    // "plugins": the skills of the plugins loaded, named as the SDK names them. A skill that
+    // `requires` a capability no active extension provides is left out; since the SDK's
+    // `skillOverrides` doesn't reach plugin skills (confirmed empirically), leaving one out takes
+    // a list: the plugins' skills and the project's, without it.
+    const missingCapabilities = await skillsMissingCapabilities(pluginRoots, resolved.capabilities);
+    const requested = spec.skills === "plugins" ? await pluginSkills(pluginRoots) : spec.skills;
+    const offeredSkills = missingCapabilities.length && (requested === undefined || requested === "all")
+        ? [...(await pluginSkills(pluginRoots)), ...((spec.settingSources ?? ["project"]).includes("project") ? await projectSkills(config.projectDir) : [])]
+        : requested;
     const skillTools = includeSkillsAndPlugins ? ["Skill"] : [];
     // Whatever opt-in subagents `spec` wants for this config, or undefined if none apply.
     // Subagents need the Agent tool (to delegate to them), and Bash when one of them uses it
@@ -121,39 +142,49 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // anything not already present here — which is why the hook, not just omitting "Bash"
     // from this list, is what actually confines it to subagent use).
     const subagents = spec.buildSubagents(config);
+    // The plugins' subagents too (agents/*.md, the agent's and its extensions'), registered as the
+    // spec's are: allowed to be spawned, counted in the Agent and Bash decision, and given the
+    // reply line (pluginAgents.ts; ADR-025).
+    // An installed extension's get no Bash (ADR-025): one without `tools` gets none.
+    const fromPlugins = {
+        ...(await pluginAgents(pluginRoots.filter((root) => !externalPlugins.has(path.resolve(root))))),
+        ...Object.fromEntries(Object.entries(await pluginAgents([...externalPlugins])).map(([name, agent]) => [name, { ...agent, tools: (agent.tools ?? []).filter((tool) => tool !== "Bash") }])),
+    };
+    const allAgents = { ...fromPlugins, ...(subagents?.agents ?? {}) };
     // Each subagent gets the reply line too: its prompt doesn't include the main one's.
-    const subagentDefinitions = subagents
-        ? Object.fromEntries(Object.entries(subagents.agents).map(([name, agent]) => [name, { ...agent, prompt: withReplyLine(agent.prompt) }]))
+    const subagentDefinitions = Object.keys(allAgents).length
+        ? Object.fromEntries(Object.entries(allAgents).map(([name, agent]) => [name, { ...agent, prompt: withReplyLine(agent.prompt) }]))
         : undefined;
-    const includeSubagentTools = subagents !== undefined;
+    const includeSubagentTools = subagentDefinitions !== undefined;
     // Bash only when a subagent can use it: one that lists it, or one without `tools`, which
     // inherits every session tool. Its definition costs about 1.9k input tokens on every call
     // (measured), and the main agent can't use it anyway.
     const subagentTools = includeSubagentTools
-        ? ["Agent", ...(Object.values(subagents.agents).some((agent) => !agent.tools || agent.tools.includes("Bash")) ? ["Bash"] : [])]
+        ? ["Agent", ...(Object.values(allAgents).some((agent) => !agent.tools || agent.tools.includes("Bash")) ? ["Bash"] : [])]
         : [];
     // The exact set of subagent_type values the Agent tool may spawn in this session — see
     // createSubagentTypeGate() below for why this can't just be "whatever's in `agents`
     // below": the SDK's own built-in "general-purpose" type is spawnable regardless of that
     // map, and inherits the full session tools (Bash included) rather than the narrow list
     // each declared subagent actually declares.
-    const allowedSubagentTypes = subagents?.allowedSubagentTypes ?? [];
+    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 ?? []);
-    // The person's preferences, by title, for the knowledge base's section (#33).
-    const preferences = knowledgeStore
-        ? (await knowledgeStore.list()).filter((page) => page.type === "preference" && page.status === "active").map(({ id, title }) => ({ id, title }))
-        : [];
     const promptSections = [
         spec.buildSystemPrompt(config),
-        ...(spec.identity ? [identityPromptSection(spec.identity)] : []),
-        // The sources' own section, with or without a knowledge base (#30).
-        ...(config.sourcesDir ? [sourcesPromptSection(config.projectDir, config.sourcesDir)] : []),
-        ...(includeKnowledgeBase && config.knowledgeDir
-            ? [knowledgePromptSection({ withSources: Boolean(config.sourcesDir), pageTypes: knowledgeStore?.types(), preferences })]
-            : []),
+        // What's on and what isn't, then the extensions' own sections.
+        ...(resolved.active.length || resolved.inactive.length ? [extensionsPromptSection(resolved)] : []),
+        // The extensions' own sections, in their order (the sources' before the knowledge base's).
+        ...fromExtensions((contribution) => (contribution.promptSection ? [contribution.promptSection] : [])),
     ];
+    // Packaged, the SDK would look for its CLI binary inside the archive, and hang (#42).
+    const claudeExecutable = unpackedClaudeExecutable();
     const sdkOptions = {
+        ...(claudeExecutable ? { pathToClaudeCodeExecutable: claudeExecutable } : {}),
         systemPrompt: withReplyLine(promptSections.join("\n\n")),
         // Not the SDK's default (every source): "user" hands the agent the runner's own Claude
         // Code configuration, and its `language` setting outranked the agent's prompt.
@@ -173,6 +204,12 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             autoMemoryEnabled: false,
             includeGitInstructions: false,
             disableClaudeAiConnectors: true,
+            // 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
@@ -208,15 +245,15 @@ 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,
                 // "skills" acts as a name whitelist, not an addition: "all" enables both the
                 // SDK's own official skills (pdf/docx), the project's own custom ones, and the
-                // plugin-provided built-ins below. A spec's own list gets the knowledge base's
-                // skills and agent-help added, so it only names its own.
-                skills: skillList(offeredSkills, includeKnowledgeBase, Boolean(helpPlugin)),
+                // plugin-provided built-ins below. A spec's own list gets the extensions' skills
+                // added, so it only names its own.
+                skills: skillList(offeredSkills, await pluginSkills(extensionPlugins), missingCapabilities),
                 plugins: pluginRoots.map((pluginPath) => ({ type: "local", path: pluginPath, skipMcpDiscovery: true })),
             }
             : {}),
@@ -227,36 +264,22 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             ...spec.buildMcpServers(config, runDir),
             ...(includeApprovalTool ? { approvals: createHumanApprovalServer(runDir, spec.humanApprovalTexts, { modeControl }) } : {}),
             ...(manualInterventionTexts ? { manualLogin: createManualLoginServer(runDir, manualInterventionTexts) } : {}),
-            // The sources folder's tools (tools/saveToSources.ts); asking a person (request_file,
-            // retire_source) only where there is one.
-            ...(config.sourcesDir
-                ? {
-                    sourceFiles: createSaveToSourcesServer(runDir, config.sourcesDir, spec.saveToSourcesDescription, {
-                        projectDir: config.projectDir,
-                        interactive: mode !== "autonomous",
-                    }),
-                }
-                : {}),
-            // The knowledge base's own tools, over its store (tools/knowledgeTools.ts, ADR-024).
-            ...(knowledgeStore
-                ? {
-                    knowledge: createKnowledgeServer(knowledgeStore, { runDir, interactive: mode !== "autonomous" }),
-                }
-                : {}),
+            // The extensions' tools (the knowledge base's, the sources').
+            ...Object.assign({}, ...added.map((contribution) => contribution.mcpServers ?? {})),
             // The date and date arithmetic, in every session and mode: only reads (tools/time.ts).
             time: createTimeServer(config.timeZone),
         },
         hooks: {
             PreToolUse: [
                 { hooks: [transcriptLogger.preToolUse] },
-                ...(includeFileTools
+                ...(fileTools.length || toolOnlyDirs.length
                     ? [{ hooks: [createFileScopeGate({
                                     projectDir: config.projectDir,
                                     writableDirs,
                                     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
@@ -264,13 +287,13 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                                     readableDirs: searchableDirs,
                                     alsoReadable: [runDir, ...pluginRoots, ...((spec.settingSources ?? ["project"]).includes("project") ? [path.join(config.projectDir, ".claude")] : [])],
                                     toolResultsRoot: claudeProjectDir(config.projectDir),
-                                    ...(includeKnowledgeBase && config.knowledgeDir ? { toolOnlyDirs: [{ dir: config.knowledgeDir, instead: "the knowledge_* tools" }] } : {}),
+                                    toolOnlyDirs,
                                 }),
                             ] }]
                     : []),
                 // Registered wherever the approval tool is, and asking only while the current mode is
                 // "interactive": a guided session can switch to interactive and back (ModeControl).
-                ...(includeApprovalTool ? [{ hooks: [createStepGate(runDir, () => modeControl.mode === "interactive")] }] : []),
+                ...(includeApprovalTool ? [{ hooks: [createStepGate(runDir, () => modeControl.mode === "interactive", fromExtensions((contribution) => contribution.selfAskingTools))] }] : []),
                 // Likewise for "plan", which any non-autonomous session can switch into: the agent
                 // only reads and plans while it's on (hooks/planGate.ts).
                 ...(includeApprovalTool
@@ -279,6 +302,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                             hooks: [
                                 createPlanGate({
                                     projectDir: config.projectDir,
+                                    readOnlyTools,
                                     ...(spec.planMode?.isPlanFile ? { isPlanFile: (filePath) => spec.planMode.isPlanFile(filePath, config) } : {}),
                                     ...(spec.planMode?.isReadOnlyTool ? { isReadOnlyTool: spec.planMode.isReadOnlyTool } : {}),
                                 }, () => modeControl.mode === "plan"),
@@ -297,7 +321,66 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             PostToolUse: [{ hooks: [transcriptLogger.postToolUse] }],
         },
     };
-    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, ...(knowledgeStore ? { knowledgeStore } : {}) };
+    // The extensions' own hooks (the memory hears the person's messages), after the kit's.
+    for (const contribution of added) {
+        for (const [event, matchers] of Object.entries(contribution.hooks ?? {})) {
+            sdkOptions.hooks[event] = [...(sdkOptions.hooks[event] ?? []), ...matchers];
+        }
+    }
+    const toolLabels = Object.assign({}, ...added.map((contribution) => contribution.toolLabels ?? {}));
+    const extensions = {
+        dirs: extensionDirs,
+        installed: await listInstalled(extensionDirs),
+        active: resolved.active.map(({ extension }) => extension.name),
+        about: Object.fromEntries(resolved.active.map(({ extension, manifest }) => [extension.name, { description: manifest.description, provides: manifest.provides }])),
+        inactive: resolved.inactive,
+    };
+    // What the session is, for the extensions that ask (sessionFacts.ts, #43).
+    const viewBase = {
+        ...(spec.identity ? { identity: spec.identity } : {}),
+        kitVersion: agentKitVersion(),
+        language,
+        extensions: {
+            active: resolved.active.map(({ extension, manifest }, index) => ({
+                name: extension.name,
+                description: manifest.description,
+                provides: manifest.provides,
+                servers: Object.keys(added[index]?.mcpServers ?? {}),
+                help: added[index]?.helpLines ?? [],
+            })),
+            // 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,
+    };
+    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 installedDir = installedDirs.get(extension.name);
+        if (!installedDir)
+            return [];
+        const contribution = added[index];
+        return [
+            {
+                name: extension.name,
+                installedDir,
+                scopeDir: path.dirname(installedDir),
+                pluginCopy: 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, switchExtension };
 }
 export { createModeControl, togglePlanMode } from "./modeControl.js";
 /** The Claude Code configuration folder the SDK's CLI uses: `CLAUDE_CONFIG_DIR`, or `~/.claude`. */
@@ -312,8 +395,21 @@ function claudeConfigDir() {
 export function claudeProjectDir(projectDir) {
     return path.join(claudeConfigDir(), "projects", path.resolve(projectDir).replace(/[^a-zA-Z0-9]/g, "-"));
 }
-/** The knowledge plugin's skills, as the SDK names a plugin's skills ("plugin:skill"). */
-const KNOWLEDGE_SKILLS = ["knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`);
+/**
+ * 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"];
 /**
  * The skills of the plugins in `roots`, as the SDK names them: `<plugin>:<folder>`, the
  * plugin's name from its `.claude-plugin/plugin.json` and the skill's folder under `skills/`,
@@ -340,10 +436,15 @@ export async function pluginSkills(roots) {
     }
     return names;
 }
-function skillList(skills, knowledgeBase, agentHelp) {
+function skillList(skills, added, leftOut) {
     if (skills === undefined || skills === "all")
         return "all";
-    return [...new Set([...skills, ...(knowledgeBase ? KNOWLEDGE_SKILLS : []), ...(agentHelp ? [AGENT_HELP_SKILL] : [])])];
+    return [...new Set([...skills, ...added])].filter((skill) => !leftOut.includes(skill));
+}
+/** The project's own skills (`<projectDir>/.claude/skills/<name>/SKILL.md`), by name. */
+async function projectSkills(projectDir) {
+    const folders = await readdir(path.join(projectDir, ".claude", "skills"), { withFileTypes: true }).catch(() => []);
+    return folders.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
 }
 /**
  * User message queue backed by a single long-lived generator, for any multi-turn

package/dist/core/sessionFacts.d.ts

@@ -0,0 +1,85 @@
+import type { Options, SlashCommand } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentIdentity, Mode } from "./agentSpec.js";
+import type { Language } from "./language.js";
+import type { ModeControl } from "./modeControl.js";
+import type { ContextUsage } from "./runner.js";
+/**
+ * What a session is, at the moment it's asked (`ExtensionContext.session()`, #43): the core's
+ * facts, read-only, never another extension's data. The mode follows Shift+Tab and plan mode;
+ * the tools, skills, commands and context come from the running session once it has started.
+ */
+export interface SessionFacts {
+    /** Who the agent is (`AgentSpec.identity`). */
+    identity?: AgentIdentity;
+    /** The agent-kit version it runs on. */
+    kitVersion: string;
+    /** The kit's language for this session. */
+    language: Language;
+    /** The mode now, and the ones the person can switch to (Shift+Tab). */
+    mode: Mode;
+    switchableModes: Mode[];
+    /** The extensions running (with their tools and what they say about themselves here), and the ones off, with why. */
+    extensions: {
+        active: {
+            name: string;
+            description: string;
+            provides: string[];
+            tools: string[];
+            help: string[];
+        }[];
+        inactive: {
+            name: string;
+            reason: string;
+        }[];
+    };
+    /** The subagents it can delegate to. */
+    subagents: {
+        name: string;
+        description: string;
+    }[];
+    /** Every tool of the session, as the model names it (empty until the session has started). */
+    tools: string[];
+    /** The skills offered (the running session's list once started; until then, the ones asked for). */
+    skills: string[];
+    /** The slash commands the person can type, with what each does (empty until the session has started). */
+    commands: {
+        name: string;
+        description: string;
+        argumentHint: string;
+    }[];
+    /** How full the context window is, when the session can tell. */
+    context?: ContextUsage;
+    /** This run's folder. */
+    runDir: string;
+}
+/** What the running session tells the view: `runQuery()` attaches it on its own. */
+export interface SessionLive {
+    tools?: string[];
+    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"> & {
+    extensions: {
+        active: (Omit<SessionFacts["extensions"]["active"][number], "tools"> & {
+            servers: string[];
+        })[];
+        inactive: SessionFacts["extensions"]["inactive"];
+    };
+};
+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;
+/** Ties a view to the options `buildSessionOptions()` returns. */
+export declare function registerSessionView(options: Options, view: SessionView): void;
+/** The view tied to these options (or a spread copy of them), if `buildSessionOptions()` built them. */
+export declare function sessionViewOf(options: Options): SessionView | undefined;

package/dist/core/sessionFacts.js

@@ -0,0 +1,49 @@
+// A live call made from inside a tool, mid-turn: never let it hold the tool up.
+const LIVE_TIMEOUT_MS = 3000;
+const within = (promise, fallback) => Promise.race([promise.catch(() => fallback), new Promise((resolve) => setTimeout(() => resolve(fallback), LIVE_TIMEOUT_MS).unref())]);
+/** The view of a session: its static facts, the mode read from `modeControl` on every call, and what the running session attaches. */
+export function createSessionView(base, modeControl) {
+    let live = {};
+    return {
+        attach(more) {
+            live = { ...live, ...more };
+        },
+        controls: () => live,
+        async facts() {
+            const tools = live.tools ?? [];
+            const [commands, context] = await Promise.all([
+                live.supportedCommands ? within(live.supportedCommands(), []) : Promise.resolve([]),
+                live.contextUsage ? within(live.contextUsage(), null) : Promise.resolve(null),
+            ]);
+            return {
+                ...base,
+                mode: modeControl.mode,
+                switchableModes: [...modeControl.switchable],
+                extensions: {
+                    active: base.extensions.active.map(({ servers, ...extension }) => ({
+                        ...extension,
+                        // The running session's names when it has started; until then, each server's wildcard.
+                        tools: tools.length ? tools.filter((tool) => servers.some((server) => tool.startsWith(`mcp__${server}__`))) : servers.map((server) => `mcp__${server}__*`),
+                    })),
+                    inactive: base.extensions.inactive,
+                },
+                tools,
+                skills: live.skills ?? base.skills,
+                commands: commands.map(({ name, description, argumentHint }) => ({ name, description, argumentHint })),
+                ...(context ? { context } : {}),
+            };
+        },
+    };
+}
+// The view rides on the options under a symbol, for runQuery() to attach the running session to
+// without the host passing anything: a spread (`{ ...options, more }`) keeps it, the SDK ignores
+// it, and options built some other way just leave the live facts out.
+const SESSION_VIEW = Symbol.for("agent-kit.sessionView");
+/** Ties a view to the options `buildSessionOptions()` returns. */
+export function registerSessionView(options, view) {
+    Object.defineProperty(options, SESSION_VIEW, { value: view, enumerable: true });
+}
+/** The view tied to these options (or a spread copy of them), if `buildSessionOptions()` built them. */
+export function sessionViewOf(options) {
+    return options[SESSION_VIEW];
+}