@falkenslab/agent-kit 0.17.0 → 0.19.0

package/dist/core/session.js

@@ -1,3 +1,5 @@
+import { readdir, readFile } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { createTranscriptLogger } from "./hooks/transcriptLogger.js";
 import { createStepGate } from "./hooks/stepGate.js";
@@ -8,18 +10,19 @@ 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 } 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 { 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
@@ -27,9 +30,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
@@ -55,57 +59,71 @@ 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;
-    // By default the agent reaches it only through the `knowledge_*` tools, over a store, never
-    // with the file tools (ADR-024); `spec.knowledgeTools: "files"` keeps the file tools on it.
-    const knowledgeViaStore = includeKnowledgeBase && (spec.knowledgeTools ?? "store") === "store";
-    const notesDir = knowledgeViaStore ? 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",
+        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 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" })));
+    const externalPlugins = new Set(resolved.active.filter(({ extension }) => extension.external).map(({ extension }) => path.resolve(extension.plugin)));
+    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 ?? [];
-    // With the store, the file tools are only for the originals (reading) and the extra writable
-    // folders; without either, none.
-    const fileTools = !includeFileTools
-        ? []
-        : !knowledgeViaStore
-            ? ["Read", "Write", "Edit", "Glob", "Grep"]
-            : [...(config.sourcesDir || extraDirs.length ? ["Read", "Glob", "Grep"] : []), ...(extraDirs.length ? ["Write", "Edit"] : [])];
+    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.
+    const wantedFileTools = new Set([
+        ...(notesDir || 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).
+    // 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 = [notesDir, ...extraDirs].filter((d) => Boolean(d));
-    const searchableDirs = [notesDir, config.sourcesDir, ...extraDirs].filter((d) => Boolean(d));
-    const readOnlyDirs = config.sourcesDir ? [config.sourcesDir] : [];
+    const searchableDirs = [notesDir, ...readOnlyDirs, ...extraDirs, ...readableExtras].filter((d) => Boolean(d));
     // 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
     // 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(knowledgeViaStore ? "tools" : "files")] : []),
-        ...(helpPlugin ? [helpPlugin] : []),
-    ];
-    const knowledgeStore = knowledgeViaStore && config.knowledgeDir
-        ? (spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(config.knowledgeDir, { pageTypes: spec.knowledgePageTypes, sourcesDir: config.sourcesDir }))
-        : undefined;
-    const includeSkillsAndPlugins = includeFileTools || pluginRoots.length > 0;
+    // 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
@@ -116,33 +134,45 @@ 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)])];
     const transcriptPath = path.join(runDir, "transcript.jsonl");
     const transcriptLogger = createTranscriptLogger(transcriptPath, config.secrets ?? []);
     const promptSections = [
         spec.buildSystemPrompt(config),
-        ...(spec.identity ? [identityPromptSection(spec.identity)] : []),
-        ...(includeKnowledgeBase && config.knowledgeDir
-            ? [knowledgePromptSection(config.projectDir, config.knowledgeDir, config.sourcesDir, { tools: knowledgeViaStore, pageTypes: knowledgeStore?.types() })]
-            : []),
+        // 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.
@@ -153,8 +183,19 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         // whose own memory is the knowledge base. includeGitInstructions: false leaves out the
         // CLI's commit workflow and git context (the runner's git user name among it), which no
         // agent here needs and which pulled replies towards the runner's language (confirmed
-        // empirically, see ADR-018).
-        settings: { autoCompactEnabled: options.autoCompactEnabled ?? true, autoMemoryEnabled: false, includeGitInstructions: false },
+        // empirically, see ADR-018). disableClaudeAiConnectors: true keeps out the claude.ai
+        // connectors of the account the session runs with (Drive, Gmail…), which the CLI fetches
+        // whatever settingSources says (confirmed empirically): the runner's integrations, not the
+        // agent's. An MCP server the agent passes itself is unaffected.
+        settings: {
+            autoCompactEnabled: options.autoCompactEnabled ?? true,
+            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 } : {}),
+        },
         // No built-in tools except, if applicable, Read/Write/Edit/Glob/Grep scoped to the
         // project's own folders (fileScopeGate below), and WebFetch/WebSearch
         // with no domain restriction (not conditioned on includeFileTools: it's read-only,
@@ -195,9 +236,9 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 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(spec.skills, includeKnowledgeBase ? (knowledgeViaStore ? "tools" : "files") : null, 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 })),
             }
             : {}),
@@ -208,49 +249,36 @@ 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, {
-                        knowledgeDir: config.knowledgeDir,
-                        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",
-                        sourcesDir: config.sourcesDir,
-                        projectDir: config.projectDir,
-                        knowledgeDir: config.knowledgeDir,
-                    }),
-                }
-                : {}),
+            // 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,
-                                    deniedPaths: config.deniedPaths ?? [],
-                                    ...(knowledgeViaStore && config.knowledgeDir ? { toolOnlyDirs: [{ dir: config.knowledgeDir, instead: "the knowledge_* tools" }] } : {}),
+                                    // The SDK's own credentials, whatever the agent denies.
+                                    deniedPaths: [...(config.deniedPaths ?? []), path.join(claudeConfigDir(), ".credentials.json")],
+                                    // 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
+                                    // projects' .env...), which an agent reading untrusted content could be talked into.
+                                    readableDirs: searchableDirs,
+                                    alsoReadable: [runDir, ...pluginRoots, ...((spec.settingSources ?? ["project"]).includes("project") ? [path.join(config.projectDir, ".claude")] : [])],
+                                    toolResultsRoot: claudeProjectDir(config.projectDir),
+                                    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
@@ -259,6 +287,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                             hooks: [
                                 createPlanGate({
                                     projectDir: config.projectDir,
+                                    readOnlyTools: fromExtensions((contribution) => contribution.readOnlyTools),
                                     ...(spec.planMode?.isPlanFile ? { isPlanFile: (filePath) => spec.planMode.isPlanFile(filePath, config) } : {}),
                                     ...(spec.planMode?.isReadOnlyTool ? { isReadOnlyTool: spec.planMode.isReadOnlyTool } : {}),
                                 }, () => modeControl.mode === "plan"),
@@ -277,18 +306,93 @@ 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).
+    late.view = createSessionView({
+        ...(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 ?? [],
+            })),
+            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);
+    registerSessionView(sdkOptions, late.view);
+    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 } : {}) };
 }
 export { createModeControl, togglePlanMode } from "./modeControl.js";
-/** The knowledge plugin's skills, as the SDK names a plugin's skills ("plugin:skill"): the tools variant has no page templates skill (knowledge_create gives them). */
-const KNOWLEDGE_SKILLS = {
-    tools: ["knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`),
-    files: ["knowledge-pages", "knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`),
-};
-function skillList(skills, knowledgeVariant, agentHelp) {
+/** The Claude Code configuration folder the SDK's CLI uses: `CLAUDE_CONFIG_DIR`, or `~/.claude`. */
+function claudeConfigDir() {
+    return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+}
+/**
+ * The CLI's folder for a project, where it keeps each session's transcript and large tool
+ * results (`<session>/tool-results/`): the project's path with every character but letters
+ * and digits as "-" (confirmed empirically).
+ */
+export function claudeProjectDir(projectDir) {
+    return path.join(claudeConfigDir(), "projects", path.resolve(projectDir).replace(/[^a-zA-Z0-9]/g, "-"));
+}
+/** 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/`,
+ * whatever its frontmatter's `name` says (confirmed empirically).
+ */
+export async function pluginSkills(roots) {
+    const names = [];
+    for (const root of roots) {
+        let plugin;
+        try {
+            plugin = JSON.parse(await readFile(path.join(root, ".claude-plugin", "plugin.json"), "utf8")).name;
+        }
+        catch {
+            continue; // not a plugin the SDK would load
+        }
+        if (!plugin)
+            continue;
+        const folders = await readdir(path.join(root, "skills"), { withFileTypes: true }).catch(() => []);
+        for (const folder of folders.filter((entry) => entry.isDirectory())) {
+            const hasSkill = await readFile(path.join(root, "skills", folder.name, "SKILL.md")).then(() => true, () => false);
+            if (hasSkill)
+                names.push(`${plugin}:${folder.name}`);
+        }
+    }
+    return names;
+}
+function skillList(skills, added, leftOut) {
     if (skills === undefined || skills === "all")
         return "all";
-    return [...new Set([...skills, ...(knowledgeVariant ? KNOWLEDGE_SKILLS[knowledgeVariant] : []), ...(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,80 @@
+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 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;
+}
+/** 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,48 @@
+// 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 };
+        },
+        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];
+}

package/dist/core/toolLabels.d.ts

@@ -1,12 +1,13 @@
+import { type ToolPhrase } from "./messages/index.js";
 /**
  * Turns a raw tool name + input into a short, readable console description, instead of
  * the tool's technical name (e.g. "mcp__playwright__browser_click"). Covers the tools
  * this kit itself provides (Read/Write/Edit/Glob/Grep/Bash/Agent/WebFetch/WebSearch/Skill,
- * plus its own human-approval/manual-intervention/save-to-sources MCP tools)
- * generically; a
- * concrete agent supplies a `describe` callback for its own domain-specific tools (e.g.
- * Playwright's browser_* cases) via `createFriendlyToolLabel()`. The kit's own labels are in
- * the current language (see messages/).
+ * plus its own human-approval/manual-intervention/clock MCP tools) generically; an extension
+ * brings its tools' labels with its contribution (`ToolLabels`, ADR-025), and a concrete agent
+ * supplies a `describe` callback for its own domain-specific tools (e.g. Playwright's
+ * browser_* cases) via `createFriendlyToolLabel()`. The kit's own labels are in the current
+ * language (see messages/).
  */
 /** Cuts `text` to `max` characters, with "…" at the end. */
 export declare function truncate(text: string, max?: number): string;
@@ -15,13 +16,30 @@ export declare function truncate(text: string, max?: number): string;
  * the tail off long freeform text), a path's most useful part, the file name, is at the end.
  */
 export declare function truncatePath(text: string, max?: number): string;
+/** How the chat shows one tool: an extension's, by its full name (`ExtensionContribution.toolLabels`). */
+export interface ToolLabel {
+    /** Its line in the chat, from its input, in the kit's language: "Reading concept/llm-wiki". */
+    label(input: Record<string, unknown>): string;
+    /** How it counts in a folded group's summary, `[one, many]` with `{n}`: `["read {n} page", "read {n} pages"]`. */
+    phrase?: ToolPhrase;
+}
+/** Tools' labels by full name (`mcp__<server>__<tool>`): what the extensions of a session bring. */
+export type ToolLabels = Readonly<Record<string, ToolLabel>>;
+/**
+ * A `formatAction` that shows the tools in `labels()` with their label, and any other with
+ * `formatAction` (the kit's by default). `labels` is read on every call, so it can follow the
+ * session in use (`/resume` opens another).
+ */
+export declare function withToolLabels(labels: () => ToolLabels | undefined, formatAction?: (toolName: string, toolInput: unknown) => string): (toolName: string, toolInput: unknown) => string;
+/** A `toolPhrase` that counts the tools in `labels()` with their phrase, and any other with `toolPhrase`. */
+export declare function withToolPhrases(labels: () => ToolLabels | undefined, toolPhrase?: (toolName: string) => ToolPhrase | undefined): (toolName: string) => ToolPhrase | undefined;
 /** An agent's labels for its own tools: the tool's short name and input, to a label, or `undefined` for the kit's default. */
 export type ToolDescriber = (shortName: string, input: Record<string, unknown>) => string | undefined;
 /**
  * Builds a `friendlyToolLabel(toolName, toolInput)` — `describe` lets the host agent
  * layer its own domain-specific cases (e.g. Playwright's browser_* tools) on top of this
  * kit's generic ones; `extraLocalServers` names any *additional* MCP server (beyond this
- * kit's own "approvals"/"manualLogin"/"sourceFiles"/"time") whose tools should be unwrapped
+ * kit's own "approvals"/"manualLogin"/"time") whose tools should be unwrapped
  * without a "[server] " prefix, e.g. "playwright".
  */
 export declare function createFriendlyToolLabel(options?: {