@falkenslab/agent-kit 0.16.1 → 0.18.0

package/README.md

@@ -38,11 +38,11 @@ A foundation for building AI agents on top of the [Claude Agent SDK](https://www
 
 See [everything he can do](https://falkenslab.github.io/agent-kit/docs/next/examples/captain-whiskers#what-he-can-do), with screenshots.
 
-### teacher-agent
+### miyagi
 
-[teacher-agent](https://github.com/falkenslab/teacher-agent) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
+[miyagi](https://github.com/falkenslab/miyagi) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
 
-Oversight, memory, safety and the chat come from the kit; teacher-agent brings what it knows about Moodle and driving the browser.
+Oversight, memory, safety and the chat come from the kit; miyagi brings what it knows about Moodle and driving the browser.
 
 ## Installation
 

package/assets/agent-help/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: agent-help
+description: How to use this agent - its chat's modes, keys and slash commands, resuming an earlier conversation, approvals and questions, the command line, and the agent's own commands and configuration. Load it whenever the person asks how to do something with you, what a key or command does, or what you can do.
+---
+
+# Helping the person use you
+
+Answer from this page only: the chat's part below is the same for every agent built on agent-kit, and the "This session" and "This agent" sections at the end are about you. If something isn't covered here, say you don't know rather than inventing a key, command or option. Answer in the language you reply in, briefly, with the exact key or command; keys and commands are typed as written here, whatever the language.
+
+## Modes
+
+How much you ask before acting. The current one is in the status bar, below the prompt.
+
+- **interactive**: asks before every single action (each tool call), with the tool and its parameters.
+- **guided**: asks only before something hard to undo or visible to others (publishing, sending); everything else runs on its own.
+- **autonomous**: never asks; there's nobody to ask. A session that starts autonomous stays autonomous.
+- **plan**: only reads and plans, changing nothing, until the plan is approved. The plan comes as a panel: **Run it** (leaves plan mode and carries it out), **Keep planning** (with a comment on what should change) or **Cancel**.
+
+`Shift+Tab` switches to the next mode the session allows (guided, interactive, plan, in a loop). `/plan` turns plan mode on, and off again back to the mode it came from.
+
+## Approvals and questions
+
+- **An approval** shows what is about to happen: **Yes** to go on, **No** to refuse that one action (the agent tries something else), **Stop** to stop it altogether.
+- **A question** with options: `↑`/`↓` and `Enter` to choose, `Space` to mark when several can be chosen, or **Other** to type your own answer. A free question: type the answer and `Enter`, or `Esc` for no answer.
+- **A request for a file**: drag the file onto the terminal (or type its path) and `Enter`, or just `Enter` if you don't have it.
+- **A manual step** (signing in by hand, for an agent that drives a window): do it, then **Done, continue**.
+- In interactive mode every action asks; switching to guided with `Shift+Tab` stops that.
+
+## Keys
+
+- `Enter` sends the message; `\` then `Enter`, or `Ctrl+J`, starts a new line.
+- `Tab` completes a `/command`, or takes the grey suggestion.
+- `↑`/`↓` go through earlier messages; `Ctrl+R` searches them. `↑` on an empty prompt edits the last message still waiting to be sent.
+- `Ctrl+W` deletes a word, `Ctrl+K` to the end of the line, `Ctrl+U` the whole line; `Ctrl+←`/`Ctrl+→` move by word.
+- `@` mentions a file, with completion.
+- `?` on an empty prompt shows the shortcuts.
+- `Esc` interrupts the agent's turn; `Ctrl+C` interrupts it, or leaves at an empty prompt.
+- `Ctrl+O` unfolds (and folds again) the tool calls; the task list of a long job stays on screen while it runs.
+- `PgUp`/`PgDn` or the mouse wheel scroll; `Ctrl+End` goes back to the bottom. In full screen, drag to select and right-click to copy.
+
+Messages typed while the agent works are queued and sent when it finishes.
+
+## Commands
+
+- `/exit` or `/quit`: leave the chat (an agent can name its own exit commands instead).
+- `/copy`: copy the last reply to the clipboard.
+- `/resume`: pick an earlier conversation to go on with (`↑`/`↓`, `Enter`, `Esc` to cancel), where the agent keeps its conversations.
+- `/plan`: plan mode on or off (see Modes).
+
+Typing `/` and `Tab` lists every command, the agent's own included (named `/plugin:command`). An unknown `/command` isn't sent.
+
+## Command line
+
+- `--continue`: start with the latest conversation instead of a new one.
+- `--language=<code>`: the language of the chat and of the replies: `en`, `es`, `fr` or `de`. Without it, the agent's configured one, or the system's.
+
+Some agents use a simpler line-by-line chat that has only part of this (no full screen, no `/copy`).

package/assets/knowledge-plugin/commands/ingest.md

@@ -4,4 +4,4 @@ description: Ingest material into the knowledge base right now - the files or to
 
 Apply the `knowledge-ingest` skill right now to: $ARGUMENTS
 
-If nothing is given above, ingest every original `list_sources` reports as new, and update the summaries of the ones it reports as changed. When you're done, summarize which pages you created and updated, and anything you couldn't read.
+If nothing is given above, ingest every original in `list_sources` that no summary is about, and update the summaries whose original's `changedAt` is after their `ingested` (both ISO 8601 in UTC: the later one sorts after as text). When you're done, summarize which pages you created and updated, and anything you couldn't read.

package/assets/knowledge-plugin/skills/knowledge-ingest/SKILL.md

@@ -9,7 +9,12 @@ A source is ingested once, and from then on the knowledge base holds what it tau
 
 ## 1. Check it isn't already ingested
 
-`list_sources` gives each original's status and summary pages: *new* needs ingesting; *ingested* has a page; *changed* changed after its ingest (update its summary). For a document from elsewhere, `knowledge_search` its title or URL.
+The sources and the knowledge base each keep their own data; you match them:
+
+- `list_sources` gives each original with `changedAt`, when its content last changed.
+- `knowledge_index` gives each summary with `file`, the original it's about, and `ingested`, when it was written.
+
+An original with no summary needs ingesting. One whose `changedAt` is after its summary's `ingested` changed since: update its summary (`knowledge_rewrite`, which sets `ingested` again). Both dates are ISO 8601 in UTC, so the later one sorts after as text; use `date_math` if in doubt. For a document from elsewhere, `knowledge_search` its title or URL.
 
 ## 2. Read it for real
 
@@ -17,7 +22,7 @@ Read the whole source, not its first page (a long PDF in parts: `list_sources` g
 
 ## 3. Write the summary page
 
-`knowledge_create` with type `summary` (call it once without content to get the template), and the field `file` (the original, relative to sources/) or `url`. Key points quote literally where exactness matters. Create the new concept and entity pages it feeds in the same call (`also`): they can link to each other.
+`knowledge_create` with type `summary` (call it once without content to get the template), and the field `file` (the original, exactly as `list_sources` names it) or `url`; `ingested` is set for you. Key points quote literally where exactness matters. Create the new concept and entity pages it feeds in the same call (`also`): they can link to each other.
 
 ## 4. Update concepts and entities
 
@@ -33,4 +38,4 @@ If the source contradicts a page, record both versions with attribution in both
 
 ## An original that was wrong or replaced
 
-`retire_source` (the person approves it) moves it aside and marks its summary retired (wrong) or superseded (replaced). Then `knowledge_check` lists the passages that cite it: after a wrong one, correct or remove what it taught (`knowledge_edit`, or `knowledge_retire` for a page that was only about it); after a replaced one, ingest the new original and re-ground those passages on it.
+`retire_source` (it asks the person itself) moves it aside; `list_sources` shows it as retired, with why and what replaced it. The knowledge base is then yours to update: find its summaries (`knowledge_index`, by `file`) and the passages that cite it (`knowledge_search` its file name). After a wrong one, `knowledge_retire` its summary (it asks the person itself: don't ask them first) and correct or remove what it taught (`knowledge_edit`, or `knowledge_retire` for a page that was only about it). After a replaced one, ingest the new original, `knowledge_supersede` the old summary by the new one, and re-ground those passages on it.

package/assets/knowledge-plugin/skills/knowledge-lint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-lint
-description: Health-check the knowledge base - broken links, orphan pages, links to retired pages, missing or changed originals, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
+description: Health-check the knowledge base - broken links, orphan pages, links to retired pages, summaries behind their originals, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
 ---
 
 # Linting the knowledge base
@@ -9,14 +9,21 @@ A knowledge base maintained across sessions drifts. Lint it when asked and after
 
 ## 1. The mechanical checks, in one call
 
-`knowledge_check` returns broken links, orphan pages, links to retired pages, summaries whose original is gone, originals that are new, changed or missing, and the passages that cite a retired original. The index and backlinks are kept by the store: there's nothing to fix there.
+`knowledge_check` returns broken links, orphan pages and links to retired pages. The index and backlinks are kept by the store: there's nothing to fix there.
 
 - **Broken links**: fix them with `knowledge_edit` when the right target is obvious (a typo, a page under a close name: `knowledge_search`); otherwise report them.
 - **Orphans**: link them from the pages where they belong, or report why they don't belong anywhere.
-- **Links to retired pages, passages citing a retired original**: correct or re-ground them.
-- **New or changed originals**: report them as what to ingest or update next (or do it, if asked).
+- **Links to retired pages**: correct or re-ground them.
 
-## 2. The checks that need judgement
+## 2. The knowledge base against its originals
+
+When there's a sources folder, match `list_sources` with `knowledge_index`:
+
+- **Not ingested**: present originals no summary is about. Report them as what to ingest next (or do it, if asked).
+- **Behind**: summaries whose original's `changedAt` is after their `ingested`, (ISO 8601 in UTC: the later one sorts after as text). Report them as what to update.
+- **Retired or missing originals**: summaries still active whose original is retired (`knowledge_retire` them if it was wrong, which asks the person itself, or `knowledge_supersede` them if it was replaced) or missing (report them); and the passages that cite them (`knowledge_search` the file name).
+
+## 3. The checks that need judgement
 
 Use `knowledge_index` and `knowledge_search`; read only the pages a check needs.
 

package/dist/core/agentHelp.d.ts

@@ -0,0 +1,30 @@
+import type { AgentIdentity, Mode } from "./agentSpec.js";
+/**
+ * The agent's self-knowledge: who it is (a section of the system prompt) and how it is used
+ * (the `agent-help` skill). The chat's part of the skill is the kit's, the same for every
+ * agent and kept next to the chat's code (`assets/agent-help/SKILL.md`, checked against the
+ * chat's commands and keys by a test); the agent's part is its own guide (`AgentSpec.helpGuide`).
+ */
+/** The plugin the skill is loaded from, as the SDK names its skills ("agent-kit:agent-help"). */
+export declare const AGENT_HELP_SKILL = "agent-kit:agent-help";
+/** Absolute path of the kit's part of the skill, next to `dist/` (or `src/` under tsx). */
+export declare function agentHelpSkillPath(): string;
+/** The "Who you are" section appended to the system prompt: name, version, what it is, the kit's version. */
+export declare function identityPromptSection(identity: AgentIdentity): string;
+/** What the generated skill says about this session. */
+export interface AgentHelpSession {
+    mode: Mode;
+    /** The modes Shift+Tab goes through (`ModeControl.switchable`). */
+    switchable: readonly Mode[];
+    /** The built-in knowledge base is on: its slash commands exist. */
+    knowledgeBase: boolean;
+    /** The sources folder, as shown to the model (e.g. "sources/"). */
+    sourcesFolder?: string;
+}
+/**
+ * Writes the `agent-help` plugin into `dir` (a folder of this run's), with the kit's part of
+ * the skill, this session's facts and the agent's own guide, and returns its root. Generated
+ * rather than shipped as it is: the guide goes inside the skill, so the agent needs no file
+ * tools to read it, and nothing about it reaches the context until the skill is loaded.
+ */
+export declare function writeAgentHelpPlugin(dir: string, session: AgentHelpSession, helpGuide?: string): Promise<string>;

package/dist/core/agentHelp.js

@@ -0,0 +1,55 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentKitVersion } from "./version.js";
+/**
+ * The agent's self-knowledge: who it is (a section of the system prompt) and how it is used
+ * (the `agent-help` skill). The chat's part of the skill is the kit's, the same for every
+ * agent and kept next to the chat's code (`assets/agent-help/SKILL.md`, checked against the
+ * chat's commands and keys by a test); the agent's part is its own guide (`AgentSpec.helpGuide`).
+ */
+/** The plugin the skill is loaded from, as the SDK names its skills ("agent-kit:agent-help"). */
+export const AGENT_HELP_SKILL = "agent-kit:agent-help";
+/** Absolute path of the kit's part of the skill, next to `dist/` (or `src/` under tsx). */
+export function agentHelpSkillPath() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "agent-help", "SKILL.md");
+}
+/** The "Who you are" section appended to the system prompt: name, version, what it is, the kit's version. */
+export function identityPromptSection(identity) {
+    const who = `${identity.name}${identity.version ? ` ${identity.version}` : ""}${identity.description ? `: ${identity.description}` : ""}`;
+    return `## Who you are
+You are ${who}. You are built on agent-kit ${agentKitVersion()}, which provides your chat (its modes, keys and slash commands) and your built-in tools.
+When the person asks how to use you (your modes, keys or commands, resuming an earlier conversation, your configuration, what you can do), load the \`agent-help\` skill and answer from it; don't invent options it doesn't list.`;
+}
+/** The skill's "This session" section. */
+function sessionSection(session) {
+    const lines = [
+        `- This session started in **${session.mode}** mode.`,
+        session.switchable.length > 1
+            ? `- \`Shift+Tab\` goes through: ${session.switchable.join(", ")}.`
+            : "- The mode can't be switched during this session.",
+    ];
+    if (session.knowledgeBase)
+        lines.push("- You keep a knowledge base (your memory across sessions). Its commands: `/knowledge:ingest` (learn the new or changed files of the sources folder), `/knowledge:query <question>` (answer from it), `/knowledge:lint` (check it and fix what's mechanical).");
+    if (session.sourcesFolder)
+        lines.push(`- Originals go in \`${session.sourcesFolder}\`: the person drops files there (or you ask for one, or download it), and you never change them.`);
+    return `## This session\n\n${lines.join("\n")}`;
+}
+/**
+ * Writes the `agent-help` plugin into `dir` (a folder of this run's), with the kit's part of
+ * the skill, this session's facts and the agent's own guide, and returns its root. Generated
+ * rather than shipped as it is: the guide goes inside the skill, so the agent needs no file
+ * tools to read it, and nothing about it reaches the context until the skill is loaded.
+ */
+export async function writeAgentHelpPlugin(dir, session, helpGuide) {
+    const kitPart = (await readFile(agentHelpSkillPath(), "utf8")).trimEnd();
+    const guide = helpGuide ? (await readFile(helpGuide, "utf8")).trim() : "";
+    const agentPart = guide
+        ? `## This agent\n\nThe agent's own guide, for everything about its domain (its commands, configuration, folders):\n\n${guide}`
+        : "## This agent\n\nThis agent has no guide of its own: for its domain, say only what your instructions tell you, and that the rest isn't documented.";
+    await mkdir(path.join(dir, ".claude-plugin"), { recursive: true });
+    await mkdir(path.join(dir, "skills", "agent-help"), { recursive: true });
+    await writeFile(path.join(dir, ".claude-plugin", "plugin.json"), `${JSON.stringify({ name: "agent-kit", description: "How to use this agent: the kit's chat and the agent's own guide." }, null, 2)}\n`);
+    await writeFile(path.join(dir, "skills", "agent-help", "SKILL.md"), `${kitPart}\n\n${sessionSection(session)}\n\n${agentPart}\n`);
+    return dir;
+}

package/dist/core/agentSpec.d.ts

@@ -40,6 +40,12 @@ export interface BaseSessionConfig {
     sourcesDir?: string;
     /** Directories besides `knowledgeDir`/`sourcesDir` where Write/Edit are allowed (see hooks/fileScopeGate.ts). */
     extraWritableDirs?: string[];
+    /**
+     * Directories besides `sourcesDir`/`extraWritableDirs` the agent may read and search (Read,
+     * Glob, Grep), never write. Read and Glob reach nothing else on the disk but what the kit
+     * knows the agent needs (see hooks/fileScopeGate.ts).
+     */
+    extraReadableDirs?: string[];
     /** Files or directories the agent must never read, search or write, e.g. a config file holding a password (see hooks/fileScopeGate.ts). */
     deniedPaths?: string[];
     /** Extra values (e.g. a password) to scrub out of the transcript log — see hooks/transcriptLogger.ts. */
@@ -70,6 +76,18 @@ export interface BaseSessionConfig {
 export interface AgentSpec<TConfig extends BaseSessionConfig> {
     /** The system prompt for this run — everything role/mode/domain-specific lives behind this call. */
     buildSystemPrompt(config: TConfig): string;
+    /**
+     * Who the agent is. With it, the kit tells the model its name, version and what it is, plus
+     * agent-kit's version, and offers the `agent-help` skill, which answers how to use the
+     * agent: the kit's chat (modes, keys, slash commands, resuming) and `helpGuide`. Without
+     * it, neither.
+     */
+    identity?: AgentIdentity;
+    /**
+     * Absolute path of a markdown guide to the agent's own domain (its commands, configuration,
+     * folders), which the `agent-help` skill includes. Only with `identity`.
+     */
+    helpGuide?: string;
     /**
      * MCP servers this agent always registers (e.g. Playwright for a browser-driving
      * agent), on top of the generic ones `buildSessionOptions()` wires up itself when
@@ -109,23 +127,15 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
     saveToSourcesDescription?: string;
     /**
      * The built-in knowledge base (see knowledge.ts): when `config.knowledgeDir` is set, the kit
-     * appends its "Knowledge base" rules to the system prompt and loads its plugin (skills
+     * appends its "Knowledge base" rules to the system prompt, loads its plugin (skills
      * knowledge-ingest/knowledge-query/knowledge-lint, commands /knowledge:ingest, /knowledge:query,
-     * /knowledge:lint), so the agent maintains its notes as an interlinked wiki, through the
-     * `knowledge_*` tools by default (see `knowledgeTools`). On by default;
-     * set `false` for an agent that writes its own rules for `knowledgeDir` (or wants plain
-     * notes) — `knowledgePromptSection()`/`knowledgePluginRoot()` are exported to reuse the pieces.
+     * /knowledge:lint) and its `knowledge_*` tools, the only way into the knowledge base (ADR-024).
+     * On by default; `false` makes `knowledgeDir` a folder of the agent's own notes, kept with the
+     * file tools under rules it writes itself.
      */
     knowledgeBase?: boolean;
     /**
-     * How the agent reaches the built-in knowledge base: `"store"` (the default), only through
-     * the kit's `knowledge_*` tools over a `KnowledgeStore`, never with the file tools, so the
-     * storage can change and the wiki's rules are kept by code (ADR-024); `"files"`, with the
-     * file tools on `knowledgeDir` and the rules in the prompt, as before.
-     */
-    knowledgeTools?: "store" | "files";
-    /**
-     * The agent's own page types for the built-in knowledge base, besides the kit's four
+     * The agent's own page types for the built-in knowledge base, besides the kit's
      * (summary, concept, entity, synthesis): each with its folder (`""` for the root), index
      * section, description (told to the model) and template.
      */
@@ -154,11 +164,13 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
     settingSources?: SettingSource[];
     /**
      * The skills the agent offers (the SDK's `skills`): names, or `plugin:skill` for a
-     * plugin's. Default `"all"`, every skill found (the SDK's own, the project's, the
-     * plugins'). A list keeps the rest out of each turn's context; the knowledge base's own
+     * plugin's. Default `"all"`, every skill found: the SDK's own (about twenty, whatever
+     * `settingSources` says), the project's, the plugins'. `"plugins"` offers only those of the
+     * plugins the session loads (`pluginRoots`, the knowledge base's, agent-help's), without
+     * naming them. A list keeps the rest out of each turn's context; the knowledge base's own
      * skills are added to it when the knowledge base is on. A context filter, not a sandbox.
      */
-    skills?: string[] | "all";
+    skills?: string[] | "all" | "plugins";
     /**
      * Text for the generic human-approval checkpoint (see tools/humanApproval.ts) — what
      * counts as "publishing something visible to others" is entirely domain-specific.
@@ -192,6 +204,15 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
      */
     planMode?: PlanModeSpec<TConfig>;
 }
+/** Who an agent is, as told to its model (`AgentSpec.identity`). */
+export interface AgentIdentity {
+    /** The agent's name, e.g. "padawan". */
+    name: string;
+    /** Its version, e.g. its package's. */
+    version?: string;
+    /** What it is, in one line, e.g. "an agent that takes a Moodle course as a student". */
+    description?: string;
+}
 /** The domain's part of "plan" mode: which files hold the plan and which of its own tools only read. */
 export interface PlanModeSpec<TConfig extends BaseSessionConfig = BaseSessionConfig> {
     /**

package/dist/core/fileKnowledgeStore.d.ts

@@ -1,10 +1,8 @@
 import { type KnowledgeStore, type PageType } from "./knowledgeStore.js";
 /** Options of `createFileKnowledgeStore()`. */
 export interface FileKnowledgeStoreOptions {
-    /** The agent's own page types, besides the kit's four. */
+    /** The agent's own page types, besides the kit's. */
     pageTypes?: readonly PageType[];
-    /** The sources folder: a summary's `file` field is given relative to it. */
-    sourcesDir?: string;
 }
 /** A `KnowledgeStore` over the markdown files of `knowledgeDir`. */
 export declare function createFileKnowledgeStore(knowledgeDir: string, options?: FileKnowledgeStoreOptions): KnowledgeStore;

package/dist/core/fileKnowledgeStore.js

@@ -27,6 +27,8 @@ 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`;
 }
+/** When a summary was written from its original (ISO 8601, as `list_sources`' `changedAt`). */
+const stampNow = () => new Date().toISOString();
 /** A `KnowledgeStore` over the markdown files of `knowledgeDir`. */
 export function createFileKnowledgeStore(knowledgeDir, options = {}) {
     const declared = options.pageTypes ?? [];
@@ -134,9 +136,9 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
         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
+            await applyFields(page, fields);
+            if (page.type.type === "summary")
+                page.fields.set("ingested", stampNow());
         }
         for (const page of ready) {
             await mkdir(path.dirname(page.file), { recursive: true });
@@ -159,28 +161,20 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
         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));
-    }
+    /**
+     * Sets or removes the fields given. `type` is the page's, and a summary's `ingested` is the
+     * store's (when it was written from its original), so neither is taken from the caller.
+     * `file` is kept as given: the original's path relative to the sources folder, which the
+     * store doesn't check (the sources are another extension's data, #30).
+     */
     async function applyFields(page, changes = {}) {
         for (const [key, value] of Object.entries(changes)) {
-            if (key === "type")
+            if (key === "type" || key === "ingested")
                 continue;
             if (value === null)
                 page.fields.delete(key);
             else
-                page.fields.set(key, await storedField(key, value, page.file));
+                page.fields.set(key, value);
         }
         page.fields.set("updated", today());
     }
@@ -191,7 +185,8 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
     }
     /** 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() {
+    /** The catalog: with links as ids (`summary/kitchen`) for the tools, or as files for `index.md`. */
+    async function indexText(links = "ids") {
         const pages = (await allPages()).filter((p) => statusOf(p) !== "retired");
         const lines = ["# Index", ""];
         for (const type of types) {
@@ -202,7 +197,7 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
             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(`- [${titleOf(page)}](${links === "ids" ? page.id : posix(path.relative(knowledgeDir, page.file))}) — ${descriptionOf(page)}${extras.length ? ` (${extras.join(", ")})` : ""}${status}`);
             }
             lines.push("");
         }
@@ -210,7 +205,7 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
     }
     async function writeIndex() {
         await mkdir(knowledgeDir, { recursive: true });
-        await writeFile(path.join(knowledgeDir, "index.md"), await indexText());
+        await writeFile(path.join(knowledgeDir, "index.md"), await indexText("files"));
     }
     async function pagesByFile() {
         const pages = await allPages();
@@ -265,6 +260,9 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
             await linksResolve(content, id);
             page.body = toFile(/^#\s/.test(content.trimStart()) ? content : `# ${titleOf(page)}\n\n${content}`, page.file);
             await applyFields(page, fields);
+            // A summary redone whole is redone from its original: written now.
+            if (page.type.type === "summary")
+                page.fields.set("ingested", stampNow());
             await save(page);
         },
         async supersede(id, by, reason) {
@@ -325,7 +323,7 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
                 .slice(0, limit)
                 .map(({ id, title, snippet }) => ({ id, title, snippet }));
         },
-        index: indexText,
+        index: () => indexText("ids"),
         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.
@@ -345,7 +343,7 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
             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: [] };
+            const report = { brokenLinks: [], orphans: [], linksToRetired: [] };
             for (const page of pages) {
                 if (statusOf(page) === "retired")
                     continue;
@@ -370,13 +368,9 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
                     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))
+                .filter((p) => statusOf(p) !== "retired" && !["summary", "synthesis", "preference"].includes(p.type.type) && !inbound.get(p.id))
                 .map((p) => p.id);
             return report;
         },

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

@@ -24,17 +24,32 @@ export interface FileScope {
         dir: string;
         instead: string;
     }[];
+    /**
+     * With it, `Read` and `Glob` are only allowed inside these (an allow-list, like
+     * `writableDirs` and `searchableDirs`), plus `alsoReadable` and the tool results under
+     * `toolResultsRoot`; `deniedPaths` still wins. Without it, they reach any path but the
+     * denied ones: any file the user can read, `~/.ssh` included.
+     */
+    readableDirs?: string[];
+    /** Readable too with `readableDirs`, but not named in a denial: the run folder, the plugin roots. */
+    alsoReadable?: string[];
+    /**
+     * The CLI's folder for this project (`~/.claude/projects/<project>`): with `readableDirs`,
+     * its sessions' `tool-results/` folders, where the SDK leaves large tool outputs for the
+     * agent to `Read`, are readable; nothing else in it.
+     */
+    toolResultsRoot?: 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;
 /**
  * The reason to deny `toolName` with `input` under `scope`, or `undefined` to let it
- * through. Tools other than Read/Write/Edit/Grep are never judged here, and a call
+ * through. Tools other than Read/Write/Edit/Grep/Glob are never judged here, and a call
  * without a path is left for the tool itself to reject.
  */
 export declare function checkFileScope(scope: FileScope, toolName: string, input: Record<string, unknown>): string | undefined;
 /**
- * PreToolUse hook enforcing `scope` on Read/Write/Edit/Grep, for the main agent and its
+ * PreToolUse hook enforcing `scope` on Read/Write/Edit/Grep/Glob, for the main agent and its
  * subagents alike. Bash, when a subagent has it, is not covered: it can reach any path,
  * which is why Bash-granting features stay opt-in.
  */

package/dist/core/hooks/fileScopeGate.js

@@ -5,11 +5,33 @@ export function isWithin(base, candidate) {
     return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
 function describeDirs(scope, dirs) {
-    return dirs.map((dir) => `${path.relative(scope.projectDir, dir) || "."}/`).join(", ");
+    return dirs.map((dir) => (isWithin(scope.projectDir, dir) ? `${path.relative(scope.projectDir, dir) || "."}/` : `${dir}/`)).join(", ");
+}
+/** Where a `Glob` really starts: its path plus the pattern's fixed folders ("sources/**" starts in sources/). */
+function globStart(scope, input) {
+    const target = typeof input.path === "string" && input.path !== "" ? path.resolve(scope.projectDir, input.path) : scope.projectDir;
+    const pattern = typeof input.pattern === "string" ? input.pattern : "";
+    return path.resolve(target, pattern.replace(/[^/\\]*[*?[{].*$/, ""));
+}
+/** Whether `target` is readable under a scope with `readableDirs`. */
+function isReadable(scope, target) {
+    const dirs = [...(scope.readableDirs ?? []), ...(scope.alsoReadable ?? [])].map((dir) => path.resolve(scope.projectDir, dir));
+    if (dirs.some((dir) => isWithin(dir, target)))
+        return true;
+    if (!scope.toolResultsRoot || !isWithin(scope.toolResultsRoot, target))
+        return false;
+    // <root>/<session>/tool-results/…, and nothing else of the CLI's (transcripts, other files).
+    return path.relative(scope.toolResultsRoot, target).split(path.sep)[1] === "tool-results";
+}
+/** The denial for reading or listing outside `readableDirs`. */
+function notReadable(scope, shown, tool) {
+    const dirs = scope.readableDirs ?? [];
+    const what = tool === "Glob" ? `Glob can't list "${String(shown)}": listing` : `"${String(shown)}" can't be read: reading`;
+    return `${what} is only allowed inside ${dirs.length ? `${describeDirs(scope, dirs)} and ` : ""}your own plugins and run folder.`;
 }
 /**
  * The reason to deny `toolName` with `input` under `scope`, or `undefined` to let it
- * through. Tools other than Read/Write/Edit/Grep are never judged here, and a call
+ * through. Tools other than Read/Write/Edit/Grep/Glob are never judged here, and a call
  * without a path is left for the tool itself to reject.
  */
 export function checkFileScope(scope, toolName, input) {
@@ -26,19 +48,32 @@ export function checkFileScope(scope, toolName, input) {
             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;
+        // Where a search really starts: Grep's path, Glob's path plus the pattern's fixed folders.
+        // From above the folder it would reach into it.
+        const start = toolName === "Glob" ? globStart(scope, input) : (resolve(input.path) ?? scope.projectDir);
         const only = toolOnly(start) ?? toolOnlyDirs.find(({ dir }) => isWithin(start, dir));
         if (only)
-            return viaTools(input.path ?? pattern, only);
+            return viaTools(input.path ?? input.pattern ?? "", only);
     }
     switch (toolName) {
         case "Read": {
             const target = resolve(input.file_path);
-            return target && isDenied(target) ? `"${input.file_path}" is off limits: it can't be read.` : undefined;
+            if (!target)
+                return undefined;
+            if (isDenied(target))
+                return `"${input.file_path}" is off limits: it can't be read.`;
+            return scope.readableDirs && !isReadable(scope, target) ? notReadable(scope, input.file_path, "Read") : undefined;
+        }
+        case "Glob": {
+            const start = globStart(scope, input);
+            const shown = input.path ?? input.pattern;
+            if (isDenied(start))
+                return `"${String(shown)}" is off limits: it can't be listed.`;
+            if (!scope.readableDirs)
+                return undefined;
+            // ".." in the pattern ("**/../../x") would climb out of where the search starts.
+            const climbs = typeof input.pattern === "string" && input.pattern.split(/[/\\]/).includes("..");
+            return climbs || !isReadable(scope, start) ? notReadable(scope, shown, "Glob") : undefined;
         }
         case "Write":
         case "Edit": {
@@ -66,7 +101,7 @@ export function checkFileScope(scope, toolName, input) {
     }
 }
 /**
- * PreToolUse hook enforcing `scope` on Read/Write/Edit/Grep, for the main agent and its
+ * PreToolUse hook enforcing `scope` on Read/Write/Edit/Grep/Glob, for the main agent and its
  * subagents alike. Bash, when a subagent has it, is not covered: it can reach any path,
  * which is why Bash-granting features stay opt-in.
  */