@falkenslab/agent-kit 0.15.0 → 0.16.1

package/dist/core/fileKnowledgeStore.js

@@ -0,0 +1,395 @@
+import { appendFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { BUILT_IN_PAGE_TYPES, isSlug, linkedIds, parseId, } from "./knowledgeStore.js";
+/**
+ * The kit's knowledge store over markdown files, in the layout the knowledge base always had
+ * (ADR-008): `index.md`, `log.md`, `overview.md` and a folder per page type (`summaries/`,
+ * `concepts/`...), or the root for a declared type with `dir: ""`. An existing knowledge base
+ * works as is. Links are stored as relative paths, so the files read well on their own, and
+ * returned as page ids; the index is rewritten after every change; backlinks are computed.
+ */
+const RESERVED = new Set(["index", "log", "overview"]);
+const posix = (p) => p.split(path.sep).join("/");
+const today = () => new Date().toISOString().slice(0, 10);
+function parse(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    const fields = new Map();
+    if (!match)
+        return { fields, body: text.replace(/^\s+/, "") };
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z_][\w-]*):\s?(.*)$/.exec(line);
+        if (kv)
+            fields.set(kv[1], kv[2].trim().replace(/^"(.*)"$/, "$1"));
+    }
+    return { fields, body: text.slice(match[0].length).replace(/^\s+/, "") };
+}
+function serialize(fields, body) {
+    const lines = [...fields].map(([key, value]) => `${key}: ${/[:#]/.test(value) && !/^\[.*\]$/.test(value) ? JSON.stringify(value) : value}`);
+    return `---\n${lines.join("\n")}\n---\n\n${body.replace(/^\s+/, "").replace(/\s*$/, "")}\n`;
+}
+/** A `KnowledgeStore` over the markdown files of `knowledgeDir`. */
+export function createFileKnowledgeStore(knowledgeDir, options = {}) {
+    const declared = options.pageTypes ?? [];
+    const types = [...BUILT_IN_PAGE_TYPES.filter((t) => !declared.some((d) => d.type === t.type)), ...declared];
+    const byType = new Map(types.map((t) => [t.type, t]));
+    const fileOf = (type, slug) => path.join(knowledgeDir, type.dir, `${slug}.md`);
+    async function readPage(type, slug) {
+        const file = fileOf(type, slug);
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch {
+            return null;
+        }
+        const { fields, body } = parse(text);
+        // At the root, a page belongs to the type its frontmatter says.
+        if (type.dir === "" && fields.get("type") !== type.type)
+            return null;
+        return { id: `${type.type}/${slug}`, type, slug, file, fields, body };
+    }
+    async function allPages() {
+        const pages = [];
+        for (const type of types) {
+            let names;
+            try {
+                names = await readdir(path.join(knowledgeDir, type.dir));
+            }
+            catch {
+                continue;
+            }
+            for (const name of names.filter((n) => n.endsWith(".md")).sort()) {
+                const slug = name.slice(0, -3);
+                if (type.dir === "" && RESERVED.has(slug))
+                    continue;
+                const page = await readPage(type, slug);
+                if (page)
+                    pages.push(page);
+            }
+        }
+        return pages;
+    }
+    async function find(id) {
+        const parsed = parseId(id);
+        const type = parsed && byType.get(parsed.type);
+        if (!parsed || !type)
+            throw new Error(`"${id}" isn't a page id: it's <type>/<slug>, with a type among ${types.map((t) => t.type).join(", ")}.`);
+        const page = await readPage(type, parsed.slug);
+        if (!page)
+            throw new Error(`There's no page "${id}". knowledge_search or knowledge_index finds the right one.`);
+        return page;
+    }
+    /** Links as ids → relative paths, from `file`. */
+    function toFile(markdown, file) {
+        return markdown.replace(/\]\(([a-z][a-z0-9-]*\/[a-z0-9]+(?:-[a-z0-9]+)*)(#[^)]*)?\)/g, (whole, id, anchor = "") => {
+            const parsed = parseId(id);
+            const type = parsed && byType.get(parsed.type);
+            if (!parsed || !type)
+                return whole;
+            return `](${posix(path.relative(path.dirname(file), fileOf(type, parsed.slug)))}${anchor})`;
+        });
+    }
+    /** Relative links to pages → ids. */
+    function fromFile(markdown, file, pagesByFile) {
+        return markdown.replace(/\]\(([^)\s:]+\.md)(#[^)]*)?\)/g, (whole, link, anchor = "") => {
+            const id = pagesByFile.get(path.normalize(path.resolve(path.dirname(file), decodeURI(link))));
+            return id ? `](${id}${anchor})` : whole;
+        });
+    }
+    const titleOf = (page) => page.fields.get("title") || /^#\s+(.+)$/m.exec(page.body)?.[1].trim() || page.slug;
+    function descriptionOf(page) {
+        const given = page.fields.get("description");
+        if (given)
+            return given;
+        const line = page.body
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .find((l) => l && !l.startsWith("#") && !l.startsWith(">") && !l.startsWith("-") && !l.startsWith("<"));
+        const sentence = (line ?? "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").split(/(?<=[.!?])\s/)[0];
+        return sentence.length > 140 ? `${sentence.slice(0, 139)}…` : sentence;
+    }
+    const statusOf = (page) => page.fields.get("status") || "active";
+    /** Checks every page first (types, slugs, ids, links among them or to existing pages), then writes them all. */
+    async function createPages(newPages) {
+        const ids = new Set();
+        const ready = [];
+        for (const { type: typeName, slug, title, content } of newPages) {
+            const type = byType.get(typeName);
+            if (!type)
+                throw new Error(`"${typeName}" isn't a page type: ${types.map((t) => t.type).join(", ")}.`);
+            if (!isSlug(slug))
+                throw new Error(`"${slug}" isn't a valid slug: lowercase ASCII words joined by hyphens, e.g. "spring-tides".`);
+            if (type.dir === "" && RESERVED.has(slug))
+                throw new Error(`"${slug}" is reserved.`);
+            const id = `${type.type}/${slug}`;
+            if (ids.has(id) || (await stat(fileOf(type, slug)).catch(() => null)))
+                throw new Error(`"${id}" already exists: edit it, or pick another slug.`);
+            ids.add(id);
+            const file = fileOf(type, slug);
+            const body = /^#\s/.test(content.trimStart()) ? content : `# ${title}\n\n${content}`;
+            ready.push({ id, type, slug, file, fields: new Map([["type", type.type], ["title", title]]), body });
+        }
+        for (const page of ready)
+            await linksResolve(page.body, page.id, ids);
+        for (const [i, page] of ready.entries()) {
+            const fields = newPages[i].fields ?? {};
+            page.body = toFile(page.body, page.file);
+            if (page.type.type === "summary" && !("ingested" in fields))
+                page.fields.set("ingested", today());
+            await applyFields(page, fields); // may refuse a summary's missing original, before anything is written
+        }
+        for (const page of ready) {
+            await mkdir(path.dirname(page.file), { recursive: true });
+            await writeFile(page.file, serialize(page.fields, page.body));
+        }
+        await writeIndex();
+        return [...ids];
+    }
+    /** Throws when a link points to a page that doesn't exist (nor is in `alsoCreating`). */
+    async function linksResolve(markdown, self, alsoCreating = new Set()) {
+        const missing = [];
+        for (const id of new Set(linkedIds(markdown))) {
+            if (id === self || alsoCreating.has(id))
+                continue;
+            const parsed = parseId(id);
+            const type = parsed && byType.get(parsed.type);
+            if (!type || !parsed || !(await readPage(type, parsed.slug)))
+                missing.push(id);
+        }
+        if (missing.length)
+            throw new Error(`These links point to pages that don't exist: ${missing.join(", ")}. Create them first, or link existing ones (knowledge_search).`);
+    }
+    /** A field given by the model, made ready to store: `file` (relative to sources/) becomes a link from the page. */
+    async function storedField(key, value, file) {
+        if (key !== "file" || !options.sourcesDir || /^[a-z]+:\/\//i.test(value))
+            return value;
+        // Relative to the sources folder; a leading "sources/" or the folder's own name is dropped.
+        let relative = value.replace(/\\/g, "/").replace(/^\.\//, "");
+        for (const prefix of ["sources/", `${path.basename(options.sourcesDir)}/`])
+            if (relative.startsWith(prefix))
+                relative = relative.slice(prefix.length);
+        const original = path.resolve(options.sourcesDir, relative);
+        if (!(await stat(original).catch(() => null))?.isFile())
+            throw new Error(`"${value}" isn't an original in sources/ (list_sources lists them).`);
+        return posix(path.relative(path.dirname(file), original));
+    }
+    async function applyFields(page, changes = {}) {
+        for (const [key, value] of Object.entries(changes)) {
+            if (key === "type")
+                continue;
+            if (value === null)
+                page.fields.delete(key);
+            else
+                page.fields.set(key, await storedField(key, value, page.file));
+        }
+        page.fields.set("updated", today());
+    }
+    async function save(page) {
+        await mkdir(path.dirname(page.file), { recursive: true });
+        await writeFile(page.file, serialize(page.fields, page.body));
+        await writeIndex();
+    }
+    /** The notice under the frontmatter of a superseded or retired page. */
+    const withNotice = (body, notice) => `> ${notice}\n\n${body.replace(/^> (Superseded|Retired) on [^\n]*\n\n/, "")}`;
+    async function indexText() {
+        const pages = (await allPages()).filter((p) => statusOf(p) !== "retired");
+        const lines = ["# Index", ""];
+        for (const type of types) {
+            const own = pages.filter((p) => p.type === type).sort((a, b) => titleOf(a).localeCompare(titleOf(b)));
+            if (!own.length)
+                continue;
+            lines.push(`## ${type.indexSection}`, "");
+            for (const page of own) {
+                const extras = (type.indexFields ?? []).filter((f) => page.fields.get(f)).map((f) => `${f}: ${page.fields.get(f)}`);
+                const status = statusOf(page) === "superseded" ? " (superseded)" : "";
+                lines.push(`- [${titleOf(page)}](${posix(path.relative(knowledgeDir, page.file))}) — ${descriptionOf(page)}${extras.length ? ` (${extras.join(", ")})` : ""}${status}`);
+            }
+            lines.push("");
+        }
+        return `${lines.join("\n").trimEnd()}\n`;
+    }
+    async function writeIndex() {
+        await mkdir(knowledgeDir, { recursive: true });
+        await writeFile(path.join(knowledgeDir, "index.md"), await indexText());
+    }
+    async function pagesByFile() {
+        const pages = await allPages();
+        return { pages, byFile: new Map(pages.map((p) => [path.normalize(p.file), p.id])) };
+    }
+    const normalize = (text) => text
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase();
+    return {
+        types: () => types,
+        async list() {
+            return (await allPages())
+                .filter((p) => statusOf(p) !== "retired")
+                .map((p) => ({ id: p.id, type: p.type.type, title: titleOf(p), description: descriptionOf(p), status: statusOf(p), fields: Object.fromEntries(p.fields) }));
+        },
+        async read(id) {
+            let page;
+            try {
+                page = await find(id);
+            }
+            catch {
+                return null;
+            }
+            const { pages, byFile } = await pagesByFile();
+            const linkedFrom = pages
+                .filter((p) => p.id !== page.id && linkedIds(fromFile(p.body, p.file, byFile)).includes(page.id))
+                .map((p) => p.id);
+            const fields = Object.fromEntries([...page.fields].filter(([key]) => key !== "type" && key !== "title"));
+            return { id: page.id, type: page.type.type, slug: page.slug, title: titleOf(page), fields, content: fromFile(page.body, page.file, byFile), linkedFrom };
+        },
+        async create(typeName, slug, title, content, fields = {}) {
+            return (await createPages([{ type: typeName, slug, title, content, fields }]))[0];
+        },
+        createMany: createPages,
+        async edit(id, oldText, newText, fields) {
+            const page = await find(id);
+            const { byFile } = await pagesByFile();
+            const current = fromFile(page.body, page.file, byFile);
+            const count = oldText ? current.split(oldText).length - 1 : 0;
+            if (count === 0)
+                throw new Error(`The text to replace isn't in "${id}" (as returned by knowledge_read, links as ids). Read it again.`);
+            if (count > 1)
+                throw new Error(`The text to replace appears ${count} times in "${id}": include more around it so it's unique.`);
+            await linksResolve(newText, id);
+            page.body = toFile(current.replace(oldText, () => newText), page.file);
+            await applyFields(page, fields);
+            await save(page);
+        },
+        async rewrite(id, content, fields) {
+            const page = await find(id);
+            await linksResolve(content, id);
+            page.body = toFile(/^#\s/.test(content.trimStart()) ? content : `# ${titleOf(page)}\n\n${content}`, page.file);
+            await applyFields(page, fields);
+            await save(page);
+        },
+        async supersede(id, by, reason) {
+            const page = await find(id);
+            const replacement = await find(by);
+            if (replacement.id === page.id)
+                throw new Error("A page can't supersede itself.");
+            const link = posix(path.relative(path.dirname(page.file), replacement.file));
+            page.fields.set("status", "superseded");
+            page.fields.set("superseded_by", link);
+            page.body = withNotice(page.body, `Superseded on ${today()}${reason ? ` (${reason})` : ""}: see [${titleOf(replacement)}](${link}).`);
+            await applyFields(page);
+            await save(page);
+        },
+        async retire(id, reason) {
+            const page = await find(id);
+            page.fields.set("status", "retired");
+            page.fields.set("retired", today());
+            page.body = withNotice(page.body, `Retired on ${today()}: ${reason}. Don't rely on what it says.`);
+            await applyFields(page);
+            await save(page);
+        },
+        async search(query, limit = 10) {
+            const terms = normalize(query)
+                .split(/[^a-z0-9]+/)
+                .filter((term) => term.length > 1);
+            if (!terms.length)
+                return [];
+            const hits = [];
+            const { pages, byFile } = await pagesByFile();
+            for (const page of pages) {
+                if (statusOf(page) === "retired")
+                    continue;
+                const title = normalize(titleOf(page));
+                const aliases = normalize(page.fields.get("aliases") ?? "");
+                const lines = fromFile(page.body, page.file, byFile)
+                    .split(/\r?\n/)
+                    .filter((line) => !/^#\s/.test(line));
+                let score = 0;
+                let snippet = "";
+                for (const term of terms) {
+                    if (title.includes(term))
+                        score += 5;
+                    if (aliases.includes(term))
+                        score += 4;
+                    for (const line of lines) {
+                        if (normalize(line).includes(term)) {
+                            score += 1;
+                            snippet ||= line.trim();
+                        }
+                    }
+                }
+                if (score > 0)
+                    hits.push({ id: page.id, title: titleOf(page), snippet: (snippet || descriptionOf(page)).slice(0, 200), score });
+            }
+            return hits
+                .sort((a, b) => b.score - a.score)
+                .slice(0, limit)
+                .map(({ id, title, snippet }) => ({ id, title, snippet }));
+        },
+        index: indexText,
+        async recentLog(limit = 10) {
+            const text = await readFile(path.join(knowledgeDir, "log.md"), "utf8").catch(() => "");
+            // Entries start with "## [date] operation | what"; the newest are at the bottom.
+            const entries = text.split(/\r?\n(?=## )/).filter((entry) => entry.startsWith("## ")).map((entry) => entry.trim());
+            return entries.slice(-limit).reverse();
+        },
+        async log(operation, what, pages = []) {
+            await mkdir(knowledgeDir, { recursive: true });
+            const file = path.join(knowledgeDir, "log.md");
+            const exists = await stat(file).catch(() => null);
+            const entry = `## [${today()}] ${operation} | ${what}\n${pages.length ? `- pages: ${pages.join(", ")}\n` : ""}`;
+            await appendFile(file, `${exists ? "\n" : "# Log\n\n"}${entry}`);
+        },
+        async check() {
+            await writeIndex(); // the one mechanical fix there is: an index.md out of date
+            const { pages, byFile } = await pagesByFile();
+            const reservedFiles = new Set([...RESERVED].map((name) => path.normalize(path.join(knowledgeDir, `${name}.md`))));
+            const known = new Map(pages.map((p) => [p.id, p]));
+            const inbound = new Map();
+            const report = { brokenLinks: [], orphans: [], linksToRetired: [], missingOriginals: [] };
+            for (const page of pages) {
+                if (statusOf(page) === "retired")
+                    continue;
+                const body = fromFile(page.body, page.file, byFile);
+                // Relative links to .md files that resolve to nothing are broken too. The overview, the
+                // index and the log aren't pages but are files: a link to one that exists is fine (a
+                // knowledge base written with the file tools links the overview, #22).
+                for (const m of page.body.matchAll(/\]\(([^)\s:]+\.md)(?:#[^)]*)?\)/g)) {
+                    const target = path.normalize(path.resolve(path.dirname(page.file), decodeURI(m[1])));
+                    if (byFile.has(target) || !target.startsWith(path.normalize(knowledgeDir)))
+                        continue;
+                    if (reservedFiles.has(target) && (await stat(target).catch(() => null)))
+                        continue;
+                    report.brokenLinks.push({ page: page.id, target: posix(path.relative(knowledgeDir, target)) });
+                }
+                for (const id of new Set(linkedIds(body))) {
+                    const target = known.get(id);
+                    if (!target)
+                        report.brokenLinks.push({ page: page.id, target: id });
+                    else if (statusOf(target) === "retired")
+                        report.linksToRetired.push({ page: page.id, target: id });
+                    if (id !== page.id)
+                        inbound.set(id, (inbound.get(id) ?? 0) + 1);
+                }
+                const file = page.fields.get("file");
+                if (file && !/^[a-z]+:\/\//i.test(file) && !(await stat(path.resolve(path.dirname(page.file), file)).catch(() => null))) {
+                    report.missingOriginals.push({ page: page.id, file });
+                }
+            }
+            report.orphans = pages
+                .filter((p) => statusOf(p) !== "retired" && p.type.type !== "summary" && p.type.type !== "synthesis" && !inbound.get(p.id))
+                .map((p) => p.id);
+            return report;
+        },
+        async overview() {
+            const file = path.join(knowledgeDir, "overview.md");
+            const text = await readFile(file, "utf8").catch(() => "");
+            return text ? fromFile(text, file, (await pagesByFile()).byFile) : "";
+        },
+        async writeOverview(content) {
+            await linksResolve(content);
+            const file = path.join(knowledgeDir, "overview.md");
+            await mkdir(knowledgeDir, { recursive: true });
+            await writeFile(file, `${toFile(content.trim(), file)}\n`);
+        },
+    };
+}

package/dist/core/hooks/fileScopeGate.d.ts

@@ -16,6 +16,14 @@ export interface FileScope {
     searchableDirs: string[];
     /** Never readable, searchable or writable. */
     deniedPaths: string[];
+    /**
+     * Reached only through the kit's own tools, never the file tools: the knowledge folder
+     * when the agent has the `knowledge_*` tools (ADR-024). The denial says what to use instead.
+     */
+    toolOnlyDirs?: {
+        dir: string;
+        instead: string;
+    }[];
 }
 /** Whether `candidate` is `base` itself or somewhere inside it (case-insensitive on Windows, like path.relative). */
 export declare function isWithin(base: string, candidate: string): boolean;

package/dist/core/hooks/fileScopeGate.js

@@ -15,6 +15,26 @@ function describeDirs(scope, dirs) {
 export function checkFileScope(scope, toolName, input) {
     const resolve = (value) => typeof value === "string" && value !== "" ? path.resolve(scope.projectDir, value) : undefined;
     const isDenied = (target) => scope.deniedPaths.some((denied) => isWithin(denied, target));
+    // The folder of the kit's own tools that `target` is in, if any.
+    const toolOnlyDirs = (scope.toolOnlyDirs ?? []).map((only) => ({ ...only, dir: path.resolve(scope.projectDir, only.dir) }));
+    const toolOnly = (target) => toolOnlyDirs.find(({ dir }) => isWithin(dir, target));
+    const viaTools = (shown, only) => `"${String(shown)}" is in ${path.relative(scope.projectDir, only.dir) || "."}/, which is reached only through ${only.instead}, not the file tools.`;
+    if (toolName === "Read" || toolName === "Write" || toolName === "Edit") {
+        const target = resolve(input.file_path);
+        const only = target && toolOnly(target);
+        if (only)
+            return viaTools(input.file_path, only);
+    }
+    if (toolName === "Grep" || toolName === "Glob") {
+        const target = resolve(input.path) ?? scope.projectDir;
+        const pattern = typeof input.pattern === "string" ? input.pattern : "";
+        // Where a search really starts: Grep's path, Glob's path plus the pattern's fixed folders
+        // ("sources/**" starts in sources/). From above the folder it would reach into it.
+        const start = toolName === "Glob" ? path.resolve(target, pattern.replace(/[^/\\]*[*?[{].*$/, "")) : target;
+        const only = toolOnly(start) ?? toolOnlyDirs.find(({ dir }) => isWithin(start, dir));
+        if (only)
+            return viaTools(input.path ?? pattern, only);
+    }
     switch (toolName) {
         case "Read": {
             const target = resolve(input.file_path);

package/dist/core/hooks/humanInput.d.ts

@@ -11,5 +11,23 @@ export type { ApprovalPrompt } from "../interaction.js";
  * Returns the answer lowercased and trimmed ("", "y", "n", "q"...).
  */
 export declare function askForDecision(runDir: string, prompt: ApprovalPrompt): Promise<string>;
+/**
+ * A free-text answer, through the port's `askText()` (or `askDecision()` when it has none)
+ * and the response file: trimmed, with its case kept.
+ */
+export declare function askForText(runDir: string, prompt: ApprovalPrompt): Promise<string>;
+/** What the person chose: the options they picked, and their own answer if they gave one. */
+export interface ChoiceAnswer {
+    chosen: string[];
+    other?: string;
+}
+/** Reads a raw choice answer (see `InteractionPort.askChoice()`) against `options`. */
+export declare function parseChoice(raw: string, options: readonly string[], multiple: boolean): ChoiceAnswer;
+/**
+ * A choice between `options`, through the port's `askChoice()` (or `askDecision()` with the
+ * options numbered in the prompt) and the response file, which takes the same answer: the
+ * numbers, or the person's own words.
+ */
+export declare function askForChoice(runDir: string, prompt: ApprovalPrompt, options: readonly string[], multiple?: boolean): Promise<ChoiceAnswer>;
 /** Like `askForDecision()`, for a manual-intervention checkpoint (see tools/manualLogin.ts). */
 export declare function askForManualIntervention(runDir: string, prompt: ApprovalPrompt): Promise<string>;

package/dist/core/hooks/humanInput.js

@@ -1,6 +1,7 @@
 import { readFile, rm } from "node:fs/promises";
 import path from "node:path";
 import { getInteractionPort } from "../interaction.js";
+import { t } from "../messages/index.js";
 /**
  * Asks the human for a decision through two channels in parallel, whichever answers
  * first wins: (1) the installed `InteractionPort` (the keyboard, for a person running the
@@ -14,6 +15,33 @@ import { getInteractionPort } from "../interaction.js";
 export async function askForDecision(runDir, prompt) {
     return await raceWithResponseFile(runDir, (port, signal) => port.askDecision(prompt, signal));
 }
+/**
+ * A free-text answer, through the port's `askText()` (or `askDecision()` when it has none)
+ * and the response file: trimmed, with its case kept.
+ */
+export async function askForText(runDir, prompt) {
+    return await raceWithResponseFile(runDir, (port, signal) => (port.askText ? port.askText(prompt, signal) : port.askDecision(prompt, signal)), false);
+}
+/** Reads a raw choice answer (see `InteractionPort.askChoice()`) against `options`. */
+export function parseChoice(raw, options, multiple) {
+    const [first = "", ...rest] = raw.trim().split(/\r?\n/);
+    const isNumbers = /^\s*\d+(\s*,\s*\d+)*\s*$/.test(first);
+    const numbers = isNumbers ? first.split(",").map((n) => Number(n.trim())).filter((n) => n >= 1 && n <= options.length) : [];
+    const chosen = [...new Set(numbers)].slice(0, multiple ? undefined : 1).map((n) => options[n - 1]);
+    const other = (isNumbers ? rest : [first, ...rest]).join("\n").trim();
+    return other ? { chosen, other } : { chosen };
+}
+/**
+ * A choice between `options`, through the port's `askChoice()` (or `askDecision()` with the
+ * options numbered in the prompt) and the response file, which takes the same answer: the
+ * numbers, or the person's own words.
+ */
+export async function askForChoice(runDir, prompt, options, multiple = false) {
+    const raw = await raceWithResponseFile(runDir, (port, signal) => port.askChoice
+        ? port.askChoice(prompt, { options, multiple }, signal)
+        : port.askDecision({ ...prompt, lines: [...prompt.lines, ...options.map((option, i) => `${i + 1}. ${option}`)], question: t().choiceQuestion(multiple) }, signal), false);
+    return parseChoice(raw, options, multiple);
+}
 /** Like `askForDecision()`, for a manual-intervention checkpoint (see tools/manualLogin.ts). */
 export async function askForManualIntervention(runDir, prompt) {
     return await raceWithResponseFile(runDir, (port, signal) => port.askManualIntervention(prompt, signal));
@@ -21,7 +49,7 @@ export async function askForManualIntervention(runDir, prompt) {
 function never() {
     return new Promise(() => { });
 }
-async function raceWithResponseFile(runDir, ask) {
+async function raceWithResponseFile(runDir, ask, lowercase = true) {
     const responseFile = path.join(runDir, "approval-response.txt");
     await rm(responseFile, { force: true });
     let settled = false;
@@ -48,5 +76,5 @@ async function raceWithResponseFile(runDir, ask) {
     settled = true;
     controller.abort();
     await rm(responseFile, { force: true });
-    return raw.trim().toLowerCase();
+    return lowercase ? raw.trim().toLowerCase() : raw.trim();
 }

package/dist/core/hooks/planGate.js

@@ -1,8 +1,17 @@
 import path from "node:path";
-/** Built-in tools that only read, search, load a skill or delegate (a subagent's own calls come through this gate too). */
-const READING_TOOLS = new Set(["Read", "Glob", "Grep", "WebFetch", "WebSearch", "Skill", "Agent"]);
-/** The kit's own MCP tools that only ask a human: approvals and manual intervention. */
-const ASKING_SERVERS = ["mcp__approvals__", "mcp__manualLogin__"];
+/** Built-in tools that only read, search, load a skill, delegate or keep the task list (a subagent's own calls come through this gate too). */
+const READING_TOOLS = new Set(["Read", "Glob", "Grep", "WebFetch", "WebSearch", "Skill", "Agent", "TodoWrite"]);
+/** The kit's own MCP servers whose tools only ask a human (approvals, manual intervention) or only read (the date and time). */
+const ASKING_SERVERS = ["mcp__approvals__", "mcp__manualLogin__", "mcp__time__"];
+/** The kit's own MCP tools that only read, on servers that also have tools that write. */
+const READING_KIT_TOOLS = new Set([
+    "mcp__sourceFiles__list_sources",
+    "mcp__sourceFiles__extract_text",
+    "mcp__knowledge__knowledge_index",
+    "mcp__knowledge__knowledge_search",
+    "mcp__knowledge__knowledge_read",
+    "mcp__knowledge__knowledge_check",
+]);
 /** Why a call is denied in plan mode, and what the model should do instead. */
 const denial = "Plan mode: nothing can be changed until the user leaves plan mode. Keep reading and researching, then present the plan; the user switches out of plan mode when they want it carried out.";
 /**
@@ -13,7 +22,7 @@ const denial = "Plan mode: nothing can be changed until the user leaves plan mod
 export function checkPlanScope(scope, toolName, input) {
     if (READING_TOOLS.has(toolName))
         return undefined;
-    if (ASKING_SERVERS.some((prefix) => toolName.startsWith(prefix)))
+    if (ASKING_SERVERS.some((prefix) => toolName.startsWith(prefix)) || READING_KIT_TOOLS.has(toolName))
         return undefined;
     if (toolName === "Write" || toolName === "Edit") {
         const target = typeof input.file_path === "string" && input.file_path !== "" ? path.resolve(scope.projectDir, input.file_path) : undefined;

package/dist/core/hooks/stepGate.js

@@ -1,5 +1,7 @@
 import { askForDecision } from "./humanInput.js";
 import { t } from "../messages/index.js";
+const SELF_ASKING_SERVERS = ["mcp__approvals__", "mcp__manualLogin__"];
+const SELF_ASKING_TOOLS = new Set(["mcp__sourceFiles__request_file", "mcp__sourceFiles__retire_source", "mcp__knowledge__knowledge_retire", "TodoWrite"]);
 /**
  * PreToolUse hook for "interactive" mode: pauses before every action and asks for
  * confirmation (by keyboard or by file, see humanInput.ts), like reviewing a plan step
@@ -14,6 +16,10 @@ export function createStepGate(runDir, isActive = () => true) {
         if (!isActive())
             return {};
         const pre = input;
+        // A tool that asks the person itself (an approval, a question, the plan, a file, retiring
+        // a source) or only keeps the task list isn't asked about first: that would be asking to ask.
+        if (SELF_ASKING_SERVERS.some((prefix) => pre.tool_name.startsWith(prefix)) || SELF_ASKING_TOOLS.has(pre.tool_name))
+            return {};
         const answer = await askForDecision(runDir, {
             title: t().proposedAction,
             lines: [t().toolLine(pre.tool_name), t().parametersLine(JSON.stringify(pre.tool_input, null, 2))],

package/dist/core/interaction.d.ts

@@ -4,6 +4,13 @@ export interface ApprovalPrompt {
     lines: string[];
     /** Terminal question text; defaults to the approve/reject one. */
     question?: string;
+    /** The lines are markdown (a plan): a UI that can render it should. */
+    markdown?: boolean;
+}
+/** How `askChoice()` asks: the options to pick from, and whether several can be picked. */
+export interface ChoiceSettings {
+    options: readonly string[];
+    multiple: boolean;
 }
 /**
  * The UI side of a human-in-the-loop checkpoint: how a host shows the question and reads a
@@ -23,6 +30,19 @@ export interface InteractionPort {
     askDecision(prompt: ApprovalPrompt, signal: AbortSignal): Promise<string>;
     /** Waits until the person confirms they intervened by hand (e.g. logged in). */
     askManualIntervention(prompt: ApprovalPrompt, signal: AbortSignal): Promise<string>;
+    /**
+     * A free-text answer (e.g. the path of a file the agent asked for), with case and spaces
+     * kept; "" for none. Optional: without it the kit asks through `askDecision()`, whose
+     * answer a plain terminal reads as text too.
+     */
+    askText?(prompt: ApprovalPrompt, signal: AbortSignal): Promise<string>;
+    /**
+     * A choice between options. Resolves to the raw answer: the chosen options' numbers
+     * (1-based, comma-separated, "1" or "1,3") on the first line, and the person's own answer
+     * ("Other") on the lines after it, or alone. Optional: without it the kit asks through
+     * `askDecision()`, with the options numbered in the prompt.
+     */
+    askChoice?(prompt: ApprovalPrompt, choice: ChoiceSettings, signal: AbortSignal): Promise<string>;
     /** A one-way message for the person. */
     notify(message: string): void;
 }

package/dist/core/knowledge.d.ts

@@ -1,3 +1,4 @@
+import type { PageType } from "./knowledgeStore.js";
 /**
  * The built-in knowledge base (an "LLM wiki"): `sourcesDir` holds the originals, `knowledgeDir`
  * is the wiki the agent writes and maintains, and the rules below plus the plugin's skills
@@ -6,10 +7,19 @@
  * with its own page types (topics, activities...) opts out with `AgentSpec.knowledgeBase: false` and
  * writes its own rules, or extends these.
  */
-/** Absolute path of the plugin shipped with the kit — `assets/knowledge-plugin` next to `dist/` (or `src/` under tsx). */
-export declare function knowledgePluginRoot(): string;
+/**
+ * Absolute path of the plugin shipped with the kit, next to `dist/` (or `src/` under tsx):
+ * `assets/knowledge-plugin`, whose skills work through the `knowledge_*` tools, or with
+ * `"files"` `assets/knowledge-plugin-files`, whose skills work on the files (ADR-024).
+ */
+export declare function knowledgePluginRoot(variant?: "tools" | "files"): string;
 /**
  * The "Knowledge base" section appended to the system prompt: the layout and the working
- * rules. The exact page templates live in the `knowledge-pages` skill, to keep this short.
+ * rules. With `tools` (the kit's default since ADR-024), for a knowledge base reached through
+ * the `knowledge_*` tools, listing `pageTypes`; otherwise for one kept with the file tools,
+ * whose page templates live in the `knowledge-pages` skill.
  */
-export declare function knowledgePromptSection(projectDir: string, knowledgeDir: string, sourcesDir?: string): string;
+export declare function knowledgePromptSection(projectDir: string, knowledgeDir: string, sourcesDir?: string, options?: {
+    tools?: boolean;
+    pageTypes?: readonly PageType[];
+}): string;