@falkenslab/agent-kit 0.10.1

package/dist/core/hooks/fileScopeGate.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+/** Whether `candidate` is `base` itself or somewhere inside it (case-insensitive on Windows, like path.relative). */
+export function isWithin(base, candidate) {
+    const relative = path.relative(base, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function describeDirs(scope, dirs) {
+    return dirs.map((dir) => `${path.relative(scope.projectDir, dir) || "."}/`).join(", ");
+}
+/**
+ * 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
+ * without a path is left for the tool itself to reject.
+ */
+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));
+    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;
+        }
+        case "Write":
+        case "Edit": {
+            const target = resolve(input.file_path);
+            if (!target)
+                return undefined;
+            if (!isDenied(target) && scope.writableDirs.some((dir) => isWithin(dir, target)))
+                return undefined;
+            if (!isDenied(target) && scope.readOnlyDirs?.some((dir) => isWithin(dir, target))) {
+                return `"${input.file_path}" is read-only: originals are never modified — write your own notes inside ${describeDirs(scope, scope.writableDirs)} instead.`;
+            }
+            return `"${input.file_path}" can't be written: writing is only allowed inside ${describeDirs(scope, scope.writableDirs)}.`;
+        }
+        case "Grep": {
+            const target = resolve(input.path) ?? scope.projectDir;
+            const inside = scope.searchableDirs.some((dir) => isWithin(dir, target));
+            // A folder that merely *contains* a denied file would still leak it through a match.
+            const containsDenied = scope.deniedPaths.some((denied) => isWithin(target, denied));
+            if (inside && !isDenied(target) && !containsDenied)
+                return undefined;
+            return `Grep only searches inside ${describeDirs(scope, scope.searchableDirs)} — pass one of them (or a folder inside) as "path".`;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * PreToolUse hook enforcing `scope` on Read/Write/Edit/Grep, 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.
+ */
+export function createFileScopeGate(scope) {
+    return async (input) => {
+        const pre = input;
+        const toolInput = pre.tool_input && typeof pre.tool_input === "object" ? pre.tool_input : {};
+        const reason = checkFileScope(scope, pre.tool_name, toolInput);
+        if (!reason)
+            return {};
+        return {
+            hookSpecificOutput: {
+                hookEventName: pre.hook_event_name,
+                permissionDecision: "deny",
+                permissionDecisionReason: reason,
+            },
+        };
+    };
+}

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

@@ -0,0 +1,15 @@
+import { type ApprovalPrompt } from "../interaction.js";
+export type { ApprovalPrompt } from "../interaction.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
+ * process in their own terminal, see tui/terminalInteraction.ts), and (2) a response file,
+ * for when something else (e.g. Claude Code, or a non-terminal host driving its own UI —
+ * an Electron main process, a Tauri sidecar) is piloting the run and has no interactive
+ * stdin to write to.
+ *
+ * Returns the answer lowercased and trimmed ("", "y", "n", "q"...).
+ */
+export declare function askForDecision(runDir: string, prompt: ApprovalPrompt): Promise<string>;
+/** 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

@@ -0,0 +1,52 @@
+import { readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { getInteractionPort } from "../interaction.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
+ * process in their own terminal, see tui/terminalInteraction.ts), and (2) a response file,
+ * for when something else (e.g. Claude Code, or a non-terminal host driving its own UI —
+ * an Electron main process, a Tauri sidecar) is piloting the run and has no interactive
+ * stdin to write to.
+ *
+ * Returns the answer lowercased and trimmed ("", "y", "n", "q"...).
+ */
+export async function askForDecision(runDir, prompt) {
+    return await raceWithResponseFile(runDir, (port, signal) => port.askDecision(prompt, signal));
+}
+/** 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));
+}
+function never() {
+    return new Promise(() => { });
+}
+async function raceWithResponseFile(runDir, ask) {
+    const responseFile = path.join(runDir, "approval-response.txt");
+    await rm(responseFile, { force: true });
+    let settled = false;
+    const controller = new AbortController();
+    const port = getInteractionPort();
+    // A port that fails to ask (e.g. a non-interactive stdin) must not win the race: let
+    // the response file answer instead.
+    const fromPort = port ? ask(port, controller.signal).catch(never) : never();
+    const fromFile = (async () => {
+        while (!settled) {
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+            try {
+                const content = (await readFile(responseFile, "utf-8")).trim();
+                if (content)
+                    return content;
+            }
+            catch {
+                // the file doesn't exist yet, keep waiting
+            }
+        }
+        return "";
+    })();
+    const raw = await Promise.race([fromPort, fromFile]);
+    settled = true;
+    controller.abort();
+    await rm(responseFile, { force: true });
+    return raw.trim().toLowerCase();
+}

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

@@ -0,0 +1,11 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * 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
+ * by step.
+ *
+ * `isActive` lets one session switch between "guided" and "interactive" while it runs (see
+ * session.ts's `ModeControl`): the hook stays registered and, while inactive, gives no
+ * decision at all, so the tool call goes on exactly as if the hook weren't there.
+ */
+export declare function createStepGate(runDir: string, isActive?: () => boolean): HookCallback;

package/dist/core/hooks/stepGate.js

@@ -0,0 +1,47 @@
+import { askForDecision } from "./humanInput.js";
+/**
+ * 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
+ * by step.
+ *
+ * `isActive` lets one session switch between "guided" and "interactive" while it runs (see
+ * session.ts's `ModeControl`): the hook stays registered and, while inactive, gives no
+ * decision at all, so the tool call goes on exactly as if the hook weren't there.
+ */
+export function createStepGate(runDir, isActive = () => true) {
+    return async (input) => {
+        if (!isActive())
+            return {};
+        const pre = input;
+        const answer = await askForDecision(runDir, {
+            title: "Proposed action",
+            lines: [`Tool: ${pre.tool_name}`, `Parameters: ${JSON.stringify(pre.tool_input, null, 2)}`],
+        });
+        if (answer === "q") {
+            return {
+                continue: false,
+                hookSpecificOutput: {
+                    hookEventName: pre.hook_event_name,
+                    permissionDecision: "deny",
+                    permissionDecisionReason: "Execution stopped manually by the user.",
+                },
+            };
+        }
+        const approved = answer === "" || answer === "y" || answer === "yes";
+        if (!approved) {
+            return {
+                hookSpecificOutput: {
+                    hookEventName: pre.hook_event_name,
+                    permissionDecision: "deny",
+                    permissionDecisionReason: "Action rejected by the user in step-by-step mode.",
+                },
+            };
+        }
+        return {
+            hookSpecificOutput: {
+                hookEventName: pre.hook_event_name,
+                permissionDecision: "allow",
+            },
+        };
+    };
+}

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

@@ -0,0 +1,28 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * PreToolUse hook restricting the Bash tool to subagents only, never the main agent
+ * directly. See session.ts's buildSessionOptions(), which attaches this hook whenever
+ * `AgentSpec.buildSubagents()` returned something for this config.
+ *
+ * Bash has to be present in the session's own `tools`/`allowedTools` for any subagent to
+ * be able to use it at all: the SDK refuses to spawn a subagent whose own
+ * `AgentDefinition.tools` names anything not already present in the session's tools
+ * ("would be spawned with zero tools... unrecognized [Bash]", confirmed empirically). But
+ * once it's there, it's also available to the main agent directly and bypasses
+ * `canUseTool` entirely for built-in tools like Bash (also confirmed empirically — this is
+ * why allowAnyMcpTool in mcpPermissions.ts, which only ever gated mcp__* tools, can't help
+ * here) — a PreToolUse hook is the mechanism the SDK's own
+ * CLAUDE_SDK_CAN_USE_TOOL_SHADOWED warning points at for gating a tool call by call.
+ *
+ * The hook input's `agent_id` field is present only when the call originates from within
+ * a subagent (confirmed empirically, matching its own doc comment in sdk.d.ts: "Absent
+ * for the main thread... Use this field (not agent_type) to distinguish subagent calls
+ * from main-thread calls.") — so denying Bash exactly when `agent_id` is absent confines
+ * it to subagent use without needing per-subagent sandboxing here. That "without needing
+ * per-subagent sandboxing" only holds together with subagentTypeGate.ts's sibling hook,
+ * registered right alongside this one in session.ts: without it, the SDK's own built-in
+ * "general-purpose" subagent_type is spawnable regardless of what `agents` declares,
+ * inherits Bash the same as an intended subagent (agent_id set either way), and has no
+ * AgentDefinition.tools list narrowing what it can do with it.
+ */
+export declare function createSubagentBashGate(): HookCallback;

package/dist/core/hooks/subagentBashGate.js

@@ -0,0 +1,40 @@
+/**
+ * PreToolUse hook restricting the Bash tool to subagents only, never the main agent
+ * directly. See session.ts's buildSessionOptions(), which attaches this hook whenever
+ * `AgentSpec.buildSubagents()` returned something for this config.
+ *
+ * Bash has to be present in the session's own `tools`/`allowedTools` for any subagent to
+ * be able to use it at all: the SDK refuses to spawn a subagent whose own
+ * `AgentDefinition.tools` names anything not already present in the session's tools
+ * ("would be spawned with zero tools... unrecognized [Bash]", confirmed empirically). But
+ * once it's there, it's also available to the main agent directly and bypasses
+ * `canUseTool` entirely for built-in tools like Bash (also confirmed empirically — this is
+ * why allowAnyMcpTool in mcpPermissions.ts, which only ever gated mcp__* tools, can't help
+ * here) — a PreToolUse hook is the mechanism the SDK's own
+ * CLAUDE_SDK_CAN_USE_TOOL_SHADOWED warning points at for gating a tool call by call.
+ *
+ * The hook input's `agent_id` field is present only when the call originates from within
+ * a subagent (confirmed empirically, matching its own doc comment in sdk.d.ts: "Absent
+ * for the main thread... Use this field (not agent_type) to distinguish subagent calls
+ * from main-thread calls.") — so denying Bash exactly when `agent_id` is absent confines
+ * it to subagent use without needing per-subagent sandboxing here. That "without needing
+ * per-subagent sandboxing" only holds together with subagentTypeGate.ts's sibling hook,
+ * registered right alongside this one in session.ts: without it, the SDK's own built-in
+ * "general-purpose" subagent_type is spawnable regardless of what `agents` declares,
+ * inherits Bash the same as an intended subagent (agent_id set either way), and has no
+ * AgentDefinition.tools list narrowing what it can do with it.
+ */
+export function createSubagentBashGate() {
+    return async (input) => {
+        const pre = input;
+        if (pre.tool_name !== "Bash" || pre.agent_id)
+            return {};
+        return {
+            hookSpecificOutput: {
+                hookEventName: pre.hook_event_name,
+                permissionDecision: "deny",
+                permissionDecisionReason: "Bash is only available to dedicated subagents, not the main agent directly — use the Agent tool to delegate to one of them instead.",
+            },
+        };
+    };
+}

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

@@ -0,0 +1,18 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * PreToolUse hook forcing `run_in_background: false` on every Agent-tool call that spawns
+ * one of this session's own subagents. The Agent tool's own input schema defaults to
+ * background execution ("Agents run in the background by default", its own description
+ * says) unless the model explicitly opts out per call — confirmed empirically (in a real
+ * consuming agent) that with a less directive prompt, the model left it on that default, the
+ * main turn's "result" fired before the subagent had done anything at all, and the whole
+ * invocation was silently lost: no file written, no error, nothing — because the caller's
+ * message loop had no code watching for background-task completion
+ * (SDKTaskStartedMessage/SDKTaskUpdatedMessage/etc. are never handled). Setting
+ * `background: false` on the AgentDefinition itself (session.ts's `agents: {...}`) does
+ * NOT fix this — confirmed empirically it has no effect on which way the model's own
+ * per-call `run_in_background` input resolves. Rewriting the tool input here, before it
+ * ever executes, is the only lever that actually forces synchronous execution regardless
+ * of what the model asked for.
+ */
+export declare function createSubagentForegroundGate(allowedTypes: readonly string[]): HookCallback;

package/dist/core/hooks/subagentForegroundGate.js

@@ -0,0 +1,34 @@
+/**
+ * PreToolUse hook forcing `run_in_background: false` on every Agent-tool call that spawns
+ * one of this session's own subagents. The Agent tool's own input schema defaults to
+ * background execution ("Agents run in the background by default", its own description
+ * says) unless the model explicitly opts out per call — confirmed empirically (in a real
+ * consuming agent) that with a less directive prompt, the model left it on that default, the
+ * main turn's "result" fired before the subagent had done anything at all, and the whole
+ * invocation was silently lost: no file written, no error, nothing — because the caller's
+ * message loop had no code watching for background-task completion
+ * (SDKTaskStartedMessage/SDKTaskUpdatedMessage/etc. are never handled). Setting
+ * `background: false` on the AgentDefinition itself (session.ts's `agents: {...}`) does
+ * NOT fix this — confirmed empirically it has no effect on which way the model's own
+ * per-call `run_in_background` input resolves. Rewriting the tool input here, before it
+ * ever executes, is the only lever that actually forces synchronous execution regardless
+ * of what the model asked for.
+ */
+export function createSubagentForegroundGate(allowedTypes) {
+    return async (input) => {
+        const pre = input;
+        if (pre.tool_name !== "Agent")
+            return {};
+        const toolInput = pre.tool_input;
+        if (!toolInput?.subagent_type || !allowedTypes.includes(toolInput.subagent_type))
+            return {};
+        if (toolInput.run_in_background === false)
+            return {}; // already foreground, nothing to change
+        return {
+            hookSpecificOutput: {
+                hookEventName: pre.hook_event_name,
+                updatedInput: { ...toolInput, run_in_background: false },
+            },
+        };
+    };
+}

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

@@ -0,0 +1,16 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * PreToolUse hook restricting the Agent tool to the subagent types this session actually
+ * registered (session.ts's `agents: {...}`, from `AgentSpec.buildSubagents()`) —
+ * confirmed empirically that the Agent SDK also exposes a built-in "general-purpose"
+ * subagent_type regardless of what `agents` lists, and that spawning one that way
+ * inherits the *whole* session's own tools (including Bash, whenever any opt-in subagent
+ * turned it on) rather than the narrow `AgentDefinition.tools` each declared subagent
+ * actually declares. Without this hook, that built-in type is a way to route around
+ * subagentBashGate.ts entirely: once inside it, `agent_id` is set exactly like an
+ * intended subagent, so the Bash-from-main-thread check alone can't tell them apart —
+ * this is exactly what happened in practice in a real consuming agent (the model delegated a plain
+ * file deletion to a spontaneous "general-purpose" agent to get at Bash, instead of using
+ * its own tools and leaving the stray file alone).
+ */
+export declare function createSubagentTypeGate(allowedTypes: readonly string[]): HookCallback;

package/dist/core/hooks/subagentTypeGate.js

@@ -0,0 +1,33 @@
+/**
+ * PreToolUse hook restricting the Agent tool to the subagent types this session actually
+ * registered (session.ts's `agents: {...}`, from `AgentSpec.buildSubagents()`) —
+ * confirmed empirically that the Agent SDK also exposes a built-in "general-purpose"
+ * subagent_type regardless of what `agents` lists, and that spawning one that way
+ * inherits the *whole* session's own tools (including Bash, whenever any opt-in subagent
+ * turned it on) rather than the narrow `AgentDefinition.tools` each declared subagent
+ * actually declares. Without this hook, that built-in type is a way to route around
+ * subagentBashGate.ts entirely: once inside it, `agent_id` is set exactly like an
+ * intended subagent, so the Bash-from-main-thread check alone can't tell them apart —
+ * this is exactly what happened in practice in a real consuming agent (the model delegated a plain
+ * file deletion to a spontaneous "general-purpose" agent to get at Bash, instead of using
+ * its own tools and leaving the stray file alone).
+ */
+export function createSubagentTypeGate(allowedTypes) {
+    return async (input) => {
+        const pre = input;
+        if (pre.tool_name !== "Agent")
+            return {};
+        const subagentType = pre.tool_input?.subagent_type;
+        if (subagentType && allowedTypes.includes(subagentType))
+            return {};
+        return {
+            hookSpecificOutput: {
+                hookEventName: pre.hook_event_name,
+                permissionDecision: "deny",
+                permissionDecisionReason: `Delegation is only available for ${allowedTypes.map((t) => `"${t}"`).join("/")} in ` +
+                    `this session, not "${subagentType ?? "(unset)"}" - do the task directly with your own ` +
+                    "tools instead of spawning another agent for it.",
+            },
+        };
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+export interface TranscriptLogger {
+    preToolUse: HookCallback;
+    postToolUse: HookCallback;
+}
+/**
+ * Logs every tool call (request + result) as one JSON line, redacting `secrets` (e.g. a
+ * domain-specific password — see `BaseSessionConfig.secrets`) plus
+ * `CLAUDE_CODE_OAUTH_TOKEN`, which this kit always scrubs regardless of domain since it
+ * owns the auth-token concept (see claudeAuth.ts).
+ */
+export declare function createTranscriptLogger(transcriptPath: string, secrets?: readonly string[]): TranscriptLogger;
+/** Avoids bloating the transcript with large payloads (browser-tool screenshots/base64). */
+export declare function summarizeToolResponse(response: unknown): unknown;

package/dist/core/hooks/transcriptLogger.js

@@ -0,0 +1,66 @@
+import { appendFile } from "node:fs/promises";
+function redact(text, secrets) {
+    let redacted = text;
+    for (const secret of secrets) {
+        if (secret)
+            redacted = redacted.split(secret).join("***");
+    }
+    return redacted;
+}
+/**
+ * Logs every tool call (request + result) as one JSON line, redacting `secrets` (e.g. a
+ * domain-specific password — see `BaseSessionConfig.secrets`) plus
+ * `CLAUDE_CODE_OAUTH_TOKEN`, which this kit always scrubs regardless of domain since it
+ * owns the auth-token concept (see claudeAuth.ts).
+ */
+export function createTranscriptLogger(transcriptPath, secrets = []) {
+    const allSecrets = [...secrets, process.env.CLAUDE_CODE_OAUTH_TOKEN].filter((s) => Boolean(s));
+    const write = async (entry) => {
+        const line = redact(JSON.stringify(entry), allSecrets);
+        await appendFile(transcriptPath, `${line}\n`, "utf-8");
+    };
+    const preToolUse = async (input) => {
+        const pre = input;
+        await write({
+            ts: new Date().toISOString(),
+            event: "pre_tool_use",
+            tool: pre.tool_name,
+            input: pre.tool_input,
+        });
+        return {};
+    };
+    const postToolUse = async (input) => {
+        const post = input;
+        await write({
+            ts: new Date().toISOString(),
+            event: "post_tool_use",
+            tool: post.tool_name,
+            result: summarizeToolResponse(post.tool_response),
+        });
+        return {};
+    };
+    return { preToolUse, postToolUse };
+}
+/** Avoids bloating the transcript with large payloads (browser-tool screenshots/base64). */
+export function summarizeToolResponse(response) {
+    const truncate = (text) => text.length > 2000 ? `${text.slice(0, 2000)}... [truncated]` : text;
+    if (typeof response === "string") {
+        return truncate(response);
+    }
+    if (Array.isArray(response)) {
+        return response.map((block) => {
+            if (block && typeof block === "object" && "type" in block) {
+                const typed = block;
+                if (typed.type === "text" && typeof typed.text === "string") {
+                    return truncate(typed.text);
+                }
+                if (typeof typed.data === "string") {
+                    return `[${typed.type} omitted, ${typed.data.length} bytes base64]`;
+                }
+                return typed;
+            }
+            return block;
+        });
+    }
+    return response;
+}

package/dist/core/interaction.d.ts

@@ -0,0 +1,29 @@
+export interface ApprovalPrompt {
+    title: string;
+    lines: string[];
+    /** Terminal question text; defaults to the approve/reject one. */
+    question?: string;
+}
+/**
+ * The UI side of a human-in-the-loop checkpoint: how a host shows the question and reads a
+ * person's answer. `askForDecision()` races it against the response file, so a port only
+ * covers the keyboard (or window) channel and never needs to know about the file.
+ *
+ * A method that can't ask (no TTY, no window) returns a promise that never resolves, so the
+ * file wins. `signal` aborts once the race is settled by the other channel; a port must
+ * drop its question then and leave its UI usable.
+ *
+ * Kept in `core/` so the checkpoints never depend on a terminal (ADR-001): the terminal
+ * port lives in `tui/` and is installed by the package entry point; a non-terminal host
+ * installs its own, or `null` to answer through the response file alone.
+ */
+export interface InteractionPort {
+    /** A step-gate or approval checkpoint; resolves to the raw answer ("", "y", "n", "q"...). */
+    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 one-way message for the person. */
+    notify(message: string): void;
+}
+export declare function setInteractionPort(port: InteractionPort | null): void;
+export declare function getInteractionPort(): InteractionPort | null;

package/dist/core/interaction.js

@@ -0,0 +1,7 @@
+let current = null;
+export function setInteractionPort(port) {
+    current = port;
+}
+export function getInteractionPort() {
+    return current;
+}

package/dist/core/knowledge.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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
+ * (knowledge-pages, knowledge-ingest, knowledge-query, knowledge-lint) and commands (/knowledge:ingest, /knowledge:query,
+ * /knowledge:lint) are the schema that tells the agent how. Domain-agnostic on purpose: an agent
+ * 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;
+/**
+ * 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.
+ */
+export declare function knowledgePromptSection(projectDir: string, knowledgeDir: string, sourcesDir?: string): string;

package/dist/core/knowledge.js

@@ -0,0 +1,54 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * 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
+ * (knowledge-pages, knowledge-ingest, knowledge-query, knowledge-lint) and commands (/knowledge:ingest, /knowledge:query,
+ * /knowledge:lint) are the schema that tells the agent how. Domain-agnostic on purpose: an agent
+ * 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 function knowledgePluginRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "knowledge-plugin");
+}
+/** A path as shown to the model: relative to the project, forward slashes, with a trailing slash. */
+function shown(projectDir, dir) {
+    return `${path.relative(projectDir, dir).split(path.sep).join("/")}/`;
+}
+/**
+ * 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.
+ */
+export function knowledgePromptSection(projectDir, knowledgeDir, sourcesDir) {
+    const notes = shown(projectDir, knowledgeDir);
+    const originals = sourcesDir ? shown(projectDir, sourcesDir) : undefined;
+    return `## Knowledge base (${notes})
+\`${notes}\` is your memory across sessions, kept as an interlinked knowledge base of markdown pages that you write and maintain yourself — a wiki, not a pile of notes. A future session only knows what is written there, so anything worth remembering must end up in a page, not just in this turn's reply. Write page content in the language you are using with the human; file names stay lowercase ASCII with hyphens.
+
+### Layers
+${originals ? `- **Originals (read-only for you)**: \`${originals}\`. Never rewrite one; build pages *about* them. Add a file there only with \`save_to_sources\`.\n` : ""}- **The knowledge base**: \`${notes}\`, entirely yours to write.
+- **The schema**: these rules plus the \`knowledge-pages\` skill (exact template of every page type — load it before creating a page) and the \`knowledge-ingest\`, \`knowledge-query\` and \`knowledge-lint\` skills.
+
+### Layout
+\`\`\`
+${notes}
+  index.md          catalog of every page, one line each: read it FIRST, always
+  log.md            append-only log of what you did to the knowledge base
+  overview.md       living synthesis of the whole knowledge base
+  summaries/<slug>.md   one page per ingested source
+  concepts/<slug>.md    one page per idea
+  entities/<slug>.md    one page per concrete thing (system, component, organization, document)
+  syntheses/<slug>.md   answers worth keeping: comparisons, analyses, reports
+\`\`\`
+
+### Working rules
+- Start by reading \`index.md\`, then only the pages the task needs — don't read the whole knowledge base.
+- Links are standard markdown links relative to the page, and go both ways: when A links to B, add the link back in B. To find who links to a page, \`Grep\` for its file name inside the knowledge base.
+- Never rename, move or delete a page (every link to it would break): if it is superseded, say so at its top and link to the new one.
+- Prefer \`Edit\` for changes to an existing page; \`Write\` only for new pages.
+- After any change, update \`index.md\` and append \`## [YYYY-MM-DD] <operation> | <what>\` to \`log.md\`, followed by the pages created/updated. Operations: \`ingest\`, \`query\`, \`lint\`, \`update\`.
+- Every claim must be traceable to a summary page, an original, or — clearly labelled as outside the knowledge base — the web.
+- Contradictions are kept, not overwritten: record both versions with attribution in the affected pages.
+- Short, focused, well-linked pages beat long ones: when a page mixes two things, split it.`;
+}

package/dist/core/mcpPermissions.d.ts

@@ -0,0 +1,23 @@
+import type { CanUseTool } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * Approves any MCP tool call ("mcp__<server>__<tool>"), regardless of which server it
+ * comes from, and denies everything else. This is what lets a project's own .mcp.json
+ * declare arbitrary additional MCP servers without the host agent's code needing to know
+ * their names ahead of time: a fixed allowedTools wildcard like "mcp__playwright__*" only
+ * matches that one named server — confirmed empirically that a bare "mcp__*" entry does
+ * NOT match "mcp__<server>__<tool>" the way a real per-server wildcard does — so a
+ * dynamic decision here is the only way to cover every MCP server generically.
+ *
+ * Dropping a .mcp.json inside a project is itself the user's opt-in (the same trust model
+ * already used for a custom skill dropped into .claude/skills/ — no separate confirmation
+ * step there either), so this approves silently rather than prompting. `disallowedTools`
+ * still takes full precedence over this — confirmed empirically that a disallowed tool
+ * never even reaches this callback, let alone executes.
+ *
+ * Every non-MCP tool the agent can use (Read/Write/Glob/WebFetch/WebSearch, ...) is
+ * normally granted via the `tools`/`allowedTools` arrays passed to `query()`, which
+ * pre-approves them before this callback would ever be consulted — so the "deny"
+ * fallback below is a defensive default for anything unexpected, not something normal
+ * operation should ever hit.
+ */
+export declare const allowAnyMcpTool: CanUseTool;

package/dist/core/mcpPermissions.js

@@ -0,0 +1,47 @@
+/**
+ * The Agent SDK emits this process warning (via process.emitWarning, confirmed by
+ * grepping the installed package) whenever canUseTool is combined with a non-empty
+ * allowedTools/tools list, to flag that the bare entries in that list (Read/Write/Glob/
+ * WebFetch/WebSearch, typically) get auto-approved before canUseTool is ever consulted.
+ * That's expected and intentional for every caller of allowAnyMcpTool below (they all
+ * pair it with exactly that setup), so suppressing it here, once, covers every case
+ * rather than repeating a warning filter per call site. A plain "warning" event listener
+ * doesn't suppress Node's own default console output (confirmed empirically: Node prints
+ * the warning regardless of registered listeners), so this patches emitWarning itself
+ * instead, letting every other warning (e.g. a real deprecation notice) through
+ * unchanged.
+ */
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, options, ...rest) => {
+    const code = typeof options === "object" && options !== null ? options.code : undefined;
+    if (code === "CLAUDE_SDK_CAN_USE_TOOL_SHADOWED")
+        return;
+    originalEmitWarning(warning, options, ...rest);
+});
+/**
+ * Approves any MCP tool call ("mcp__<server>__<tool>"), regardless of which server it
+ * comes from, and denies everything else. This is what lets a project's own .mcp.json
+ * declare arbitrary additional MCP servers without the host agent's code needing to know
+ * their names ahead of time: a fixed allowedTools wildcard like "mcp__playwright__*" only
+ * matches that one named server — confirmed empirically that a bare "mcp__*" entry does
+ * NOT match "mcp__<server>__<tool>" the way a real per-server wildcard does — so a
+ * dynamic decision here is the only way to cover every MCP server generically.
+ *
+ * Dropping a .mcp.json inside a project is itself the user's opt-in (the same trust model
+ * already used for a custom skill dropped into .claude/skills/ — no separate confirmation
+ * step there either), so this approves silently rather than prompting. `disallowedTools`
+ * still takes full precedence over this — confirmed empirically that a disallowed tool
+ * never even reaches this callback, let alone executes.
+ *
+ * Every non-MCP tool the agent can use (Read/Write/Glob/WebFetch/WebSearch, ...) is
+ * normally granted via the `tools`/`allowedTools` arrays passed to `query()`, which
+ * pre-approves them before this callback would ever be consulted — so the "deny"
+ * fallback below is a defensive default for anything unexpected, not something normal
+ * operation should ever hit.
+ */
+export const allowAnyMcpTool = async (toolName, input) => {
+    if (toolName.startsWith("mcp__")) {
+        return { behavior: "allow", updatedInput: input };
+    }
+    return { behavior: "deny", message: `"${toolName}" isn't an allowed tool in this session.` };
+};