@falkenslab/agent-kit 0.15.0 → 0.16.1

package/dist/core/messages/fr.js

@@ -54,6 +54,29 @@ export const fr = {
     parametersLine: (parameters) => `Paramètres : ${parameters}`,
     approvalTitle: "Confirmation humaine requise avant de publier",
     summaryLine: (summary) => `Résumé : ${summary}`,
+    noAnswer: "(pas de réponse)",
+    textAnswerHint: "tapez la réponse",
+    textAnswerKeys: "Entrée pour envoyer · Échap pour ne pas répondre",
+    fileRequestTitle: "L'agent demande un fichier",
+    fileRequestQuestion: "Chemin du fichier (glissez-le ici), ou Entrée si vous ne l'avez pas : ",
+    retireTitle: "Retirer une source ?",
+    retirePageTitle: "Retirer une page de la base de connaissances ?",
+    choiceQuestion: (multiple) => (multiple ? "Numéros séparés par des virgules, ou votre propre réponse : " : "Numéro, ou votre propre réponse : "),
+    otherOption: "Autre (tapez votre réponse)",
+    choiceKeys: (multiple) => (multiple ? "Espace pour cocher · Entrée pour envoyer" : "↑/↓ choisir · Entrée pour envoyer"),
+    questionTitle: "L'agent demande",
+    planTitle: "Le plan, pour votre approbation",
+    runPlan: "L'exécuter",
+    keepPlanning: "Continuer à planifier",
+    cancelPlan: "Annuler",
+    planCommentQuestion: "Que faut-il changer ? (Entrée pour passer) : ",
+    retireLines: (source, why, reason, replacedBy, folder) => [
+        `Source : ${source}`,
+        why === "wrong" ? "Motif : elle est erronée ; son résumé sera retiré" : "Motif : elle est remplacée ; son résumé sera marqué comme remplacé",
+        `Raison : ${reason}`,
+        ...(replacedBy ? [`Remplacée par : ${replacedBy}`] : []),
+        `Elle est déplacée dans ${folder}.agent-kit/retired/, pas supprimée.`,
+    ],
     toolPhrases: {
         Read: ["a lu {n} fichier", "a lu {n} fichiers"],
         Write: ["a écrit {n} fichier", "a écrit {n} fichiers"],
@@ -66,6 +89,26 @@ export const fr = {
         Skill: ["a utilisé {n} skill", "a utilisé {n} skills"],
         Agent: ["a lancé {n} sous-agent", "a lancé {n} sous-agents"],
         Task: ["a lancé {n} sous-agent", "a lancé {n} sous-agents"],
+        mcp__time__current_time: ["a consulté l'heure", "a consulté l'heure {n} fois"],
+        mcp__time__date_math: ["a calculé des dates", "a calculé des dates {n} fois"],
+        mcp__sourceFiles__list_sources: ["a examiné les sources", "a examiné les sources {n} fois"],
+        mcp__sourceFiles__extract_text: ["a lu {n} document", "a lu {n} documents"],
+        mcp__sourceFiles__save_to_sources: ["a enregistré {n} source", "a enregistré {n} sources"],
+        mcp__sourceFiles__download_to_sources: ["a téléchargé {n} source", "a téléchargé {n} sources"],
+        mcp__sourceFiles__request_file: ["a demandé {n} fichier", "a demandé {n} fichiers"],
+        mcp__sourceFiles__retire_source: ["a retiré {n} source", "a retiré {n} sources"],
+        mcp__knowledge__knowledge_index: ["a lu l'index", "a lu l'index {n} fois"],
+        mcp__knowledge__knowledge_search: ["a cherché dans la base", "a cherché dans la base {n} fois"],
+        mcp__knowledge__knowledge_read: ["a lu {n} page", "a lu {n} pages"],
+        mcp__knowledge__knowledge_create: ["a créé {n} page", "a créé {n} pages"],
+        mcp__knowledge__knowledge_edit: ["a modifié {n} page", "a modifié {n} pages"],
+        mcp__knowledge__knowledge_rewrite: ["a réécrit {n} page", "a réécrit {n} pages"],
+        mcp__knowledge__knowledge_supersede: ["a remplacé {n} page", "a remplacé {n} pages"],
+        mcp__knowledge__knowledge_retire: ["a retiré {n} page", "a retiré {n} pages"],
+        mcp__knowledge__knowledge_log: ["a mis à jour le journal", "a mis à jour le journal {n} fois"],
+        mcp__knowledge__knowledge_check: ["a vérifié la base", "a vérifié la base {n} fois"],
+        mcp__approvals__ask_human: ["a posé {n} question", "a posé {n} questions"],
+        mcp__approvals__present_plan: ["a présenté le plan", "a présenté le plan {n} fois"],
     },
     otherTools: ["a utilisé {n} outil", "a utilisé {n} outils"],
     noOutput: "(aucune sortie)",
@@ -73,10 +116,13 @@ export const fr = {
     toolFailed: "Impossible de terminer",
     moreResultLines: (count) => `(+${count} ${plural(count, "ligne", "lignes")})`,
     earlierCalls: (count) => `… ${count} ${plural(count, "précédent", "précédents")}`,
+    moreTodos: (count) => `… ${count} ${plural(count, "tâche", "tâches")} de plus`,
     labels: {
         askingApproval: (summary) => `Demande d'approbation humaine : ${summary}`,
         waitingManual: "En attente d'une intervention manuelle",
-        savingToSources: (destination) => `Enregistrement d'un fichier dans sources/${destination}`,
+        savingToSources: (destination) => `Enregistrement de ${destination} dans les sources`,
+        checkingTime: "Consultation de la date et de l'heure",
+        calculatingDates: "Calcul de dates",
         reading: (file) => `Lecture de ${file}`,
         writing: (file) => `Écriture dans ${file}`,
         editing: (file) => `Modification de ${file}`,
@@ -92,6 +138,24 @@ export const fr = {
         searchingWeb: (query) => `Recherche sur le web de "${query}"`,
         applyingSkill: (skill) => `Application de la skill "${skill}"`,
         aSkill: "une skill",
+        updatingTasks: "Mise à jour de la liste des tâches",
+        listingSources: "Examen des sources",
+        extractingText: (source) => `Lecture de ${source}`,
+        downloading: (url) => `Téléchargement de ${url} dans les sources`,
+        requestingFile: (description) => `Demande d'un fichier : ${description}`,
+        retiringSource: (source) => `Retrait de la source ${source}`,
+        knowledgeIndex: "Lecture de l'index de la base de connaissances",
+        knowledgeSearch: (query) => `Recherche de "${query}" dans la base de connaissances`,
+        knowledgeRead: (page) => `Lecture de ${page}`,
+        knowledgeCreate: (page) => `Création de ${page}`,
+        knowledgeEdit: (page) => `Modification de ${page}`,
+        knowledgeRewrite: (page) => `Réécriture de ${page}`,
+        knowledgeSupersede: (page) => `${page} marquée comme remplacée`,
+        knowledgeRetire: (page) => `Retrait de ${page}`,
+        knowledgeLog: "Mise à jour du journal de la base de connaissances",
+        knowledgeCheck: "Vérification de la base de connaissances",
+        askingHuman: (question) => `Question : ${question}`,
+        presentingPlan: "Présentation du plan",
     },
     auth: {
         noToken: "Aucun jeton d'authentification Claude n'a été trouvé",

package/dist/core/modeControl.d.ts

@@ -0,0 +1,36 @@
+import type { Mode } from "./agentSpec.js";
+/**
+ * The supervision mode of a running session. "guided", "interactive" and "plan" switch into
+ * one another: they share the same tools (the approval tool), and the step gate and the plan
+ * gate are registered in all three, deciding only in their own mode. "autonomous" has no
+ * approval tool at all, and a tool can't appear or vanish mid-session, so a session that
+ * starts autonomous stays autonomous, and one that doesn't can't become autonomous. The
+ * system prompt keeps the mode it was built with, so entering or leaving plan mode is told
+ * to the model with the next message instead (`takeNotice()`).
+ */
+export interface ModeControl {
+    readonly mode: Mode;
+    /** The modes this session can be in, in Shift+Tab's order; fewer than two means it can't switch. */
+    readonly switchable: readonly Mode[];
+    /** Switches to `next` if this session allows it; returns whether it did. */
+    set(next: Mode): boolean;
+    /**
+     * The note telling the model it entered or left plan mode, once per change it hasn't been
+     * told about yet; `undefined` otherwise. `createInputQueue({ modeControl })` puts it before
+     * the next message; a caller with its own queue prepends it itself.
+     */
+    takeNotice?(): string | undefined;
+    /**
+     * Calls `listener` with the new mode whenever it changes (Shift+Tab, `/plan`, or the agent
+     * leaving plan mode through `present_plan`), so a UI can show it; returns the unsubscribe.
+     */
+    subscribe?(listener: (mode: Mode) => void): () => void;
+}
+/** A `ModeControl` starting at `initial` (`buildSessionOptions()` returns one for its session). */
+export declare function createModeControl(initial: Mode): ModeControl;
+/**
+ * What the chats' `/plan` does: switches `control` into plan mode, or, when it's already
+ * there, back to the mode it was entered from ("guided" if it started in plan mode). Returns
+ * the new mode, or `null` when this session can't be in plan mode (an autonomous one).
+ */
+export declare function togglePlanMode(control: ModeControl): Mode | null;

package/dist/core/modeControl.js

@@ -0,0 +1,61 @@
+/** A `ModeControl` starting at `initial` (`buildSessionOptions()` returns one for its session). */
+export function createModeControl(initial) {
+    let current = initial;
+    // The mode the model was last told about: a session starting in plan mode tells it with
+    // the first message, since the system prompt doesn't say.
+    let told = initial === "plan" ? undefined : initial;
+    const switchable = initial === "autonomous" ? ["autonomous"] : ["guided", "interactive", "plan"];
+    const listeners = new Set();
+    return {
+        get mode() {
+            return current;
+        },
+        switchable,
+        set(next) {
+            if (!switchable.includes(next))
+                return false;
+            const changed = next !== current;
+            current = next;
+            if (changed)
+                for (const listener of listeners)
+                    listener(next);
+            return true;
+        },
+        takeNotice() {
+            const before = told;
+            told = current;
+            if (current === "plan" && before !== "plan")
+                return PLAN_MODE_ENTERED;
+            if (current !== "plan" && before === "plan")
+                return PLAN_MODE_LEFT;
+            return undefined;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+// The mode each session was in when `/plan` took it into plan mode, to go back to.
+const modeBeforePlan = new WeakMap();
+/**
+ * What the chats' `/plan` does: switches `control` into plan mode, or, when it's already
+ * there, back to the mode it was entered from ("guided" if it started in plan mode). Returns
+ * the new mode, or `null` when this session can't be in plan mode (an autonomous one).
+ */
+export function togglePlanMode(control) {
+    if (!control.switchable.includes("plan"))
+        return null;
+    if (control.mode === "plan") {
+        const back = modeBeforePlan.get(control) ?? "guided";
+        control.set(back);
+        return back;
+    }
+    modeBeforePlan.set(control, control.mode);
+    control.set("plan");
+    return "plan";
+}
+// What the model reads on a plan-mode switch, in English like the rest of what it reads
+// (ADR-019); tagged so a resumed conversation doesn't show it as the human's words (runs.ts).
+const PLAN_MODE_ENTERED = "<system-reminder>The user switched to plan mode. Only read, research and plan: nothing can be changed (files, tools that modify something) until they switch out of it. When the plan is ready, present it and wait for them.</system-reminder>";
+const PLAN_MODE_LEFT = "<system-reminder>The user left plan mode: you can carry out the plan now.</system-reminder>";

package/dist/core/session.d.ts

@@ -1,6 +1,8 @@
 import type { Options, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import { type TranscriptLogger } from "./hooks/transcriptLogger.js";
-import type { AgentSpec, BaseSessionConfig, Mode } from "./agentSpec.js";
+import { type ModeControl } from "./modeControl.js";
+import type { KnowledgeStore } from "./knowledgeStore.js";
+import type { AgentSpec, BaseSessionConfig } from "./agentSpec.js";
 import { type Language } from "./language.js";
 import { type RunFolder } from "./runs.js";
 /**
@@ -31,37 +33,10 @@ export declare function buildSessionOptions<TConfig extends BaseSessionConfig>(c
     transcriptPath: string;
     modeControl: ModeControl;
     language: Language;
+    /** The knowledge base's store, when the agent reaches it through the `knowledge_*` tools. */
+    knowledgeStore?: KnowledgeStore;
 }>;
-/**
- * The supervision mode of a running session. "guided", "interactive" and "plan" switch into
- * one another: they share the same tools (the approval tool), and the step gate and the plan
- * gate are registered in all three, deciding only in their own mode. "autonomous" has no
- * approval tool at all, and a tool can't appear or vanish mid-session, so a session that
- * starts autonomous stays autonomous, and one that doesn't can't become autonomous. The
- * system prompt keeps the mode it was built with, so entering or leaving plan mode is told
- * to the model with the next message instead (`takeNotice()`).
- */
-export interface ModeControl {
-    readonly mode: Mode;
-    /** The modes this session can be in, in Shift+Tab's order; fewer than two means it can't switch. */
-    readonly switchable: readonly Mode[];
-    /** Switches to `next` if this session allows it; returns whether it did. */
-    set(next: Mode): boolean;
-    /**
-     * The note telling the model it entered or left plan mode, once per change it hasn't been
-     * told about yet; `undefined` otherwise. `createInputQueue({ modeControl })` puts it before
-     * the next message; a caller with its own queue prepends it itself.
-     */
-    takeNotice?(): string | undefined;
-}
-/** A `ModeControl` starting at `initial` (`buildSessionOptions()` returns one for its session). */
-export declare function createModeControl(initial: Mode): ModeControl;
-/**
- * What the chats' `/plan` does: switches `control` into plan mode, or, when it's already
- * there, back to the mode it was entered from ("guided" if it started in plan mode). Returns
- * the new mode, or `null` when this session can't be in plan mode (an autonomous one).
- */
-export declare function togglePlanMode(control: ModeControl): Mode | null;
+export { createModeControl, togglePlanMode, type ModeControl } from "./modeControl.js";
 /**
  * User message queue backed by a single long-lived generator, for any multi-turn
  * (chat-shaped) caller of `query()`.

package/dist/core/session.js

@@ -9,6 +9,11 @@ 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 { allowAnyMcpTool } from "./mcpPermissions.js";
 import { knowledgePluginRoot, knowledgePromptSection } from "./knowledge.js";
 import { replyLanguageInstruction } from "./language.js";
@@ -53,24 +58,38 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // (`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);
-    const fileTools = includeFileTools ? ["Read", "Write", "Edit", "Glob", "Grep"] : [];
+    // 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;
+    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"] : [])];
     // 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 = [config.knowledgeDir, ...(config.extraWritableDirs ?? [])].filter((d) => Boolean(d));
-    const searchableDirs = [config.knowledgeDir, config.sourcesDir, ...(config.extraWritableDirs ?? [])].filter((d) => Boolean(d));
+    const writableDirs = [notesDir, ...extraDirs].filter((d) => Boolean(d));
+    const searchableDirs = [notesDir, config.sourcesDir, ...extraDirs].filter((d) => Boolean(d));
     const readOnlyDirs = config.sourcesDir ? [config.sourcesDir] : [];
     // 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.
-    // 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;
-    const pluginRoots = [...spec.pluginRoots(config), ...(includeKnowledgeBase ? [knowledgePluginRoot()] : [])];
+    const pluginRoots = [...spec.pluginRoots(config), ...(includeKnowledgeBase ? [knowledgePluginRoot(knowledgeViaStore ? "tools" : "files")] : [])];
+    const knowledgeStore = knowledgeViaStore && config.knowledgeDir
+        ? (spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(config.knowledgeDir, { pageTypes: spec.knowledgePageTypes, sourcesDir: config.sourcesDir }))
+        : undefined;
     const includeSkillsAndPlugins = includeFileTools || pluginRoots.length > 0;
     const skillTools = includeSkillsAndPlugins ? ["Skill"] : [];
     // Whatever opt-in subagents `spec` wants for this config, or undefined if none apply.
@@ -97,7 +116,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     const transcriptLogger = createTranscriptLogger(transcriptPath, config.secrets ?? []);
     const sdkOptions = {
         systemPrompt: withReplyLine(includeKnowledgeBase && config.knowledgeDir
-            ? `${spec.buildSystemPrompt(config)}\n\n${knowledgePromptSection(config.projectDir, config.knowledgeDir, config.sourcesDir)}`
+            ? `${spec.buildSystemPrompt(config)}\n\n${knowledgePromptSection(config.projectDir, config.knowledgeDir, config.sourcesDir, { tools: knowledgeViaStore, pageTypes: knowledgeStore?.types() })}`
             : spec.buildSystemPrompt(config)),
         // 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.
@@ -118,8 +137,10 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         // "Skill" has to be listed explicitly: with an explicit `tools` list the SDK loads the
         // skills (they show up in the init message) but doesn't offer the tool to invoke them,
         // so the model ends up looking for SKILL.md files by hand (confirmed empirically).
-        tools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
-        allowedTools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
+        // TodoWrite: the SDK's task list for long jobs, in every session (the chats show the list
+        // instead of the calls; see todos.ts). Accepted in an explicit list (confirmed empirically).
+        tools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", TODO_TOOL, ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
+        allowedTools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", TODO_TOOL, ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
         // Every mcp__* tool (whatever spec.buildMcpServers() registers, approvals/manualLogin
         // when enabled below, sourceFiles, and any server a project's own .mcp.json
         // declares) is approved generically here rather than listed one by one — see
@@ -127,6 +148,11 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         // name isn't known ahead of time.
         canUseTool: allowAnyMcpTool,
         disallowedTools: spec.disallowedTools ?? [],
+        // TodoWrite (todos.ts) only exists with CLAUDE_CODE_ENABLE_TASKS=0: by default the CLI
+        // offers its TaskCreate/TaskUpdate/TaskList/TaskGet tools instead, and drops TodoWrite from
+        // the session even when `tools` names it (confirmed empirically). `env` replaces the
+        // subprocess environment, so the rest is passed on as it is.
+        env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" },
         // Real text streaming instead of silently waiting for the turn's complete message —
         // see the caller's message loop.
         includePartialMessages: true,
@@ -145,7 +171,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 // 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 added, so it only names its own.
-                skills: skillList(spec.skills, includeKnowledgeBase),
+                skills: skillList(spec.skills, includeKnowledgeBase ? (knowledgeViaStore ? "tools" : "files") : null),
                 plugins: pluginRoots.map((pluginPath) => ({ type: "local", path: pluginPath, skipMcpDiscovery: true })),
             }
             : {}),
@@ -154,15 +180,47 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         ...(subagentDefinitions ? { agents: subagentDefinitions } : {}),
         mcpServers: {
             ...spec.buildMcpServers(config, runDir),
-            ...(includeApprovalTool ? { approvals: createHumanApprovalServer(runDir, spec.humanApprovalTexts) } : {}),
+            ...(includeApprovalTool ? { approvals: createHumanApprovalServer(runDir, spec.humanApprovalTexts, { modeControl }) } : {}),
             ...(manualInterventionTexts ? { manualLogin: createManualLoginServer(runDir, manualInterventionTexts) } : {}),
-            ...(config.sourcesDir ? { sourceFiles: createSaveToSourcesServer(runDir, config.sourcesDir, spec.saveToSourcesDescription) } : {}),
+            // 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 date and date arithmetic, in every session and mode: only reads (tools/time.ts).
+            time: createTimeServer(config.timeZone),
         },
         hooks: {
             PreToolUse: [
                 { hooks: [transcriptLogger.preToolUse] },
                 ...(includeFileTools
-                    ? [{ hooks: [createFileScopeGate({ projectDir: config.projectDir, writableDirs, searchableDirs, readOnlyDirs, deniedPaths: config.deniedPaths ?? [] })] }]
+                    ? [{ hooks: [createFileScopeGate({
+                                    projectDir: config.projectDir,
+                                    writableDirs,
+                                    searchableDirs,
+                                    readOnlyDirs,
+                                    deniedPaths: config.deniedPaths ?? [],
+                                    ...(knowledgeViaStore && config.knowledgeDir ? { toolOnlyDirs: [{ dir: config.knowledgeDir, instead: "the knowledge_* tools" }] } : {}),
+                                }),
+                            ] }]
                     : []),
                 // 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).
@@ -193,67 +251,19 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             PostToolUse: [{ hooks: [transcriptLogger.postToolUse] }],
         },
     };
-    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language };
+    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, ...(knowledgeStore ? { knowledgeStore } : {}) };
 }
-/** The knowledge plugin's skills, as the SDK names a plugin's skills ("plugin:skill"). */
-const KNOWLEDGE_SKILLS = ["knowledge-pages", "knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`);
-function skillList(skills, includeKnowledgeBase) {
+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) {
     if (skills === undefined || skills === "all")
         return "all";
-    return includeKnowledgeBase ? [...new Set([...skills, ...KNOWLEDGE_SKILLS])] : skills;
-}
-/** A `ModeControl` starting at `initial` (`buildSessionOptions()` returns one for its session). */
-export function createModeControl(initial) {
-    let current = initial;
-    // The mode the model was last told about: a session starting in plan mode tells it with
-    // the first message, since the system prompt doesn't say.
-    let told = initial === "plan" ? undefined : initial;
-    const switchable = initial === "autonomous" ? ["autonomous"] : ["guided", "interactive", "plan"];
-    return {
-        get mode() {
-            return current;
-        },
-        switchable,
-        set(next) {
-            if (!switchable.includes(next))
-                return false;
-            current = next;
-            return true;
-        },
-        takeNotice() {
-            const before = told;
-            told = current;
-            if (current === "plan" && before !== "plan")
-                return PLAN_MODE_ENTERED;
-            if (current !== "plan" && before === "plan")
-                return PLAN_MODE_LEFT;
-            return undefined;
-        },
-    };
-}
-// The mode each session was in when `/plan` took it into plan mode, to go back to.
-const modeBeforePlan = new WeakMap();
-/**
- * What the chats' `/plan` does: switches `control` into plan mode, or, when it's already
- * there, back to the mode it was entered from ("guided" if it started in plan mode). Returns
- * the new mode, or `null` when this session can't be in plan mode (an autonomous one).
- */
-export function togglePlanMode(control) {
-    if (!control.switchable.includes("plan"))
-        return null;
-    if (control.mode === "plan") {
-        const back = modeBeforePlan.get(control) ?? "guided";
-        control.set(back);
-        return back;
-    }
-    modeBeforePlan.set(control, control.mode);
-    control.set("plan");
-    return "plan";
+    return knowledgeVariant ? [...new Set([...skills, ...KNOWLEDGE_SKILLS[knowledgeVariant]])] : skills;
 }
-// What the model reads on a plan-mode switch, in English like the rest of what it reads
-// (ADR-019); tagged so a resumed conversation doesn't show it as the human's words (runs.ts).
-const PLAN_MODE_ENTERED = "<system-reminder>The user switched to plan mode. Only read, research and plan: nothing can be changed (files, tools that modify something) until they switch out of it. When the plan is ready, present it and wait for them.</system-reminder>";
-const PLAN_MODE_LEFT = "<system-reminder>The user left plan mode: you can carry out the plan now.</system-reminder>";
 /**
  * User message queue backed by a single long-lived generator, for any multi-turn
  * (chat-shaped) caller of `query()`.

package/dist/core/sources.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The sources folder's bookkeeping: originals stay files (ADR-024), and the kit keeps a
+ * manifest next to them (`.agent-kit/sources.json`, inside `sourcesDir`, where the agent's
+ * file tools can't write) with each original's hash, size and provenance, the version it
+ * replaces, and the hash it had when a summary page first pointed to it. From that it tells
+ * new, ingested, changed and missing originals apart, refuses duplicates, and retires an
+ * original into `.agent-kit/retired/` instead of deleting it.
+ */
+export declare const KIT_DIR = ".agent-kit";
+/** Where an original came from. */
+export type SourceOrigin = {
+    kind: "run";
+    from: string;
+} | {
+    kind: "url";
+    from: string;
+} | {
+    kind: "person";
+    from: string;
+}
+/** Copied in by hand: first seen by `listSources()`. */
+ | {
+    kind: "manual";
+};
+export interface SourceEntry {
+    hash: string;
+    size: number;
+    /** For hashing a file again only when it changed. */
+    mtimeMs: number;
+    addedAt: string;
+    origin: SourceOrigin;
+    /** The original this one is a new version of (a path relative to `sourcesDir`). */
+    replaces?: string;
+    /** The page this one was generated from (a web page's markdown, from its HTML). */
+    derivedFrom?: string;
+    /** The hash when a summary page first pointed to it: a different hash now means it changed after its ingest. */
+    ingestedHash?: string;
+}
+export interface RetiredSource {
+    path: string;
+    movedTo: string;
+    retiredAt: string;
+    why: "wrong" | "replaced";
+    reason: string;
+    replacedBy?: string;
+    entry?: SourceEntry;
+}
+export interface SourceManifest {
+    version: 1;
+    files: Record<string, SourceEntry>;
+    retired: RetiredSource[];
+}
+export type SourceStatus = "new" | "ingested" | "changed" | "missing" | "present";
+export interface SourceListing {
+    path: string;
+    status: SourceStatus;
+    type: string;
+    size?: number;
+    pages?: number;
+    slides?: number;
+    origin?: SourceOrigin;
+    replaces?: string;
+    /** The summary pages that point to it (paths relative to the project). */
+    summaries: string[];
+}
+export declare function hashFile(file: string): Promise<string>;
+/** Resolves `candidate` against `base`; the absolute path only if it stays inside it. */
+export declare function resolveWithin(base: string, candidate: string): string | undefined;
+export declare function loadManifest(sourcesDir: string): Promise<SourceManifest>;
+export declare function saveManifest(sourcesDir: string, manifest: SourceManifest): Promise<void>;
+/** Every original under `sourcesDir` (paths relative to it), leaving out hidden files and folders (the kit's own among them). */
+export declare function scanSources(sourcesDir: string): Promise<string[]>;
+/** The summary pages (knowledge base layout: `summaries/*.md`) by the absolute path of the original their frontmatter `file:` points to. */
+export declare function summariesByOriginal(knowledgeDir: string): Promise<Map<string, string[]>>;
+/** Pages of a PDF, read from its page tree without a parser; undefined when it can't tell (e.g. compressed object streams). */
+export declare function pdfPageCount(bytes: Buffer): number | undefined;
+/** Slides of a PPTX, from the file names in the zip (stored uncompressed). */
+export declare function pptxSlideCount(bytes: Buffer): number | undefined;
+/**
+ * Every original with its status, recording in the manifest the ones copied in by hand and,
+ * the first time a summary page points to one, its hash at ingest. Without a knowledge
+ * folder there's no ingest to compare with: originals are "present".
+ */
+export declare function listSources(sourcesDir: string, knowledgeDir: string | undefined, projectDir: string): Promise<SourceListing[]>;
+export interface AddedSource {
+    /** Where it is, relative to `sourcesDir`. */
+    path: string;
+    /** An identical file was already there: nothing was copied. */
+    duplicateOf?: string;
+}
+/**
+ * Adds `file` (an absolute path) to `sourcesDir` at `destination` (a folder: under `extra.name`,
+ * or the file's own name): never overwriting, and
+ * not at all if an identical file is already there (its path is returned). `replaces`
+ * records it as a new version of an original already in the folder.
+ */
+export declare function addSource(sourcesDir: string, file: string, destination: string, origin: SourceOrigin, extra?: {
+    replaces?: string;
+    derivedFrom?: string;
+    name?: string;
+}): Promise<AddedSource>;
+/** What retiring an original did to its summary pages (paths relative to the project). */
+export interface RetireResult {
+    movedTo: string;
+    summaries: {
+        page: string;
+        marked: "retired" | "superseded";
+        supersededBy?: string;
+    }[];
+}
+/**
+ * Moves an original to `.agent-kit/retired/` (never deleted: the person empties that folder)
+ * and records why. Its summary pages are marked: retired if the original was wrong (what it
+ * taught was wrong), superseded if it was replaced, pointing to the replacement's summary
+ * when there is one.
+ */
+export declare function retireSource(sourcesDir: string, knowledgeDir: string | undefined, projectDir: string, source: string, why: "wrong" | "replaced", reason: string, replacedBy?: string): Promise<RetireResult>;
+/**
+ * Records `source` (relative to `sourcesDir`) as ingested now, with its current hash: a
+ * summary page was just written from it, so "changed" means changed after this.
+ */
+export declare function recordIngest(sourcesDir: string, source: string): Promise<void>;