@falkenslab/agent-kit 0.25.0 → 0.27.0

package/dist/chat/extensions.d.ts

@@ -39,6 +39,20 @@ export type ExtensionAction = {
 export declare function describeEntry(entry: CatalogEntry): string;
 /** An installed extension's options, one line each: its value, its default, or whether a sensitive one is set (never its value). */
 export declare function describeOptions(extension: InstalledExtension): Promise<string[]>;
+/** What guided mode keeps about an extension's tools (#74, #76): whether they ask, and the answers kept. None for one without tools. */
+export declare function describeConfirm(extension: InstalledExtension): string[];
+/**
+ * `confirm=on|off|reset` among `config`'s pairs (#74, #76): `off` lets its tools run without asking
+ * in guided mode, `on` asks again, `reset` forgets the answers kept. Returns the other pairs and
+ * the extension as it is now, or why it can't.
+ */
+export declare function applyConfirm(extension: InstalledExtension, pairs: readonly string[]): Promise<{
+    rest: string[];
+    extension: InstalledExtension;
+    changed: boolean;
+} | {
+    error: string;
+}>;
 /**
  * `/extensions` in a chat (#37): with nothing after it, what the session runs with, what's off
  * and why, and what's installed; with `enable <name>` or `disable <name>`, changes its lock and

package/dist/chat/extensions.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { extensionOptionStates, setExtensionEnabled, setExtensionOptions } from "../core/externalExtensions.js";
+import { extensionOptionStates, readLock, setExtensionConfirm, setExtensionEnabled, setExtensionOptions } from "../core/externalExtensions.js";
 import { t } from "../core/messages/index.js";
 import { extensionCatalog } from "../core/extensionCatalog.js";
 /** One line for an installed extension: name and version, scope, on or off, its author, where it came from. */
@@ -54,6 +54,31 @@ export async function describeOptions(extension) {
         return `  ${key} = ${shown}  (${option.title}${option.required ? `, ${t().optionRequired}` : ""})`;
     });
 }
+/** What guided mode keeps about an extension's tools (#74, #76): whether they ask, and the answers kept. None for one without tools. */
+export function describeConfirm(extension) {
+    if (!Object.keys(extension.manifest?.servers ?? {}).length)
+        return [];
+    const confirm = extension.lock.confirm;
+    if (confirm?.off)
+        return [t().extensionConfirmOff(extension.name)];
+    const kept = Object.entries(confirm?.tools ?? {});
+    return [t().extensionConfirmOn(extension.name), ...(kept.length ? kept.map(([tool, answer]) => t().confirmKept(tool, answer)) : [t().confirmNoneKept])];
+}
+/**
+ * `confirm=on|off|reset` among `config`'s pairs (#74, #76): `off` lets its tools run without asking
+ * in guided mode, `on` asks again, `reset` forgets the answers kept. Returns the other pairs and
+ * the extension as it is now, or why it can't.
+ */
+export async function applyConfirm(extension, pairs) {
+    const rest = pairs.filter((pair) => !pair.startsWith("confirm="));
+    const values = pairs.filter((pair) => pair.startsWith("confirm=")).map((pair) => pair.slice("confirm=".length).toLowerCase());
+    if (values.some((value) => !["on", "off", "reset"].includes(value)))
+        return { error: "confirm takes on, off or reset" };
+    for (const value of values)
+        await setExtensionConfirm(extension.scopeDir, extension.name, value === "reset" ? { reset: true } : { off: value === "off" });
+    const lock = values.length ? (await readLock(extension.scopeDir))[extension.name] : undefined;
+    return { rest, extension: lock ? { ...extension, lock } : extension, changed: values.length > 0 };
+}
 /**
  * `/extensions` in a chat (#37): with nothing after it, what the session runs with, what's off
  * and why, and what's installed; with `enable <name>` or `disable <name>`, changes its lock and
@@ -96,10 +121,16 @@ export async function chatExtensionsCommand(line, status, canReopen) {
             return { lines: [t().extensionNotInstalled(name)] };
         if (!extra.length) {
             const options = await describeOptions(installed);
-            return { lines: options.length ? [t().extensionOptions(name), ...options] : [t().extensionNoOptions(name)] };
+            return { lines: [...(options.length ? [t().extensionOptions(name), ...options] : [t().extensionNoOptions(name)]), ...describeConfirm(installed)] };
         }
+        // Guided mode's answers: the gate reads them on each call, so nothing restarts (#74, #76).
+        const confirm = await applyConfirm(installed, extra);
+        if ("error" in confirm)
+            return { lines: [`(${confirm.error})`] };
+        if (!confirm.rest.length)
+            return { lines: describeConfirm(confirm.extension) };
         const typed = {};
-        for (const pair of extra) {
+        for (const pair of confirm.rest) {
             const at = pair.indexOf("=");
             const key = at > 0 ? pair.slice(0, at) : pair;
             if (installed.manifest?.userConfig[key]?.sensitive)
@@ -120,6 +151,11 @@ export async function chatExtensionsCommand(line, status, canReopen) {
         const lines = [status?.active.length ? t().extensionsRunning(status.active.join(", ")) : t().extensionsNone];
         if (status)
             lines.push(...describeCapabilities(status), ...(await needingSignIn(status)).map((extension) => t().extensionNeedsSignIn(extension)));
+        // The claude.ai connectors the agent lets in, apart from installed extensions (#70).
+        if (status?.connectors?.allowed.length)
+            lines.push(t().connectorsAllowed(status.connectors.allowed.map((name) => name.replace(/^claude\.ai /, "")).join(", ")));
+        if (status?.connectors?.missing.length)
+            lines.push(t().connectorsMissing(status.connectors.missing.join(", ")));
         for (const { name: off, reason } of status?.inactive ?? [])
             lines.push(t().extensionOff(off, reason));
         if (status?.installed.length)

package/dist/core/agentSpec.d.ts

@@ -44,6 +44,22 @@ export interface BaseSessionConfig {
      * catalog and `extension search` show only those with one of them. Without it, every one.
      */
     catalogTopics?: string[];
+    /**
+     * The claude.ai connectors of the person's account this agent lets in (#70), by the name
+     * claude.ai shows them (`["Canva", "Notion"]`, any case): those already signed in on claude.ai,
+     * nothing to install. None by default: the kit keeps them out, since they're the account's
+     * integrations, not the agent's. When the session opens, the kit asks the account which it has
+     * (a few seconds) and lets in only these; one asked for that isn't there is said in `/extensions`.
+     */
+    claudeAiConnectors?: string[];
+    /**
+     * What a call to a remote MCP server does (#70): an installed extension's `http`/`sse` server, one
+     * of the agent's own, or a claude.ai connector. What the model sends one leaves the computer, so
+     * an agent handling sensitive data (students') may keep it from them. `"allow"` (the default)
+     * lets it go on; `"ask"` asks the person before each call, saying where it goes (blocked when no
+     * one can be asked, as in autonomous mode); `"deny"` blocks it.
+     */
+    remoteServers?: "allow" | "ask" | "deny";
     /**
      * Directories where the agent reads, searches and writes with the file tools (Write/Edit,
      * scoped — see hooks/fileScopeGate.ts), e.g. a folder of its own notes. Setting one gives the
@@ -170,6 +186,11 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
         approved: string;
         rejected: string;
     };
+    /**
+     * Guided mode's gate for installed extensions' tools that change things (#74, #76, see
+     * hooks/guidedGate.ts): one that isn't known to only read waits for the person's yes. On by default.
+     */
+    extensionGate?: ExtensionGateSpec;
     /**
      * Text for the generic manual-intervention checkpoint (see tools/manualLogin.ts), AND
      * this domain's opt-in signal for offering that checkpoint at all: `buildSessionOptions()`
@@ -193,6 +214,18 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
      */
     planMode?: PlanModeSpec<TConfig>;
 }
+/** The agent's word on guided mode's gate for extensions' tools (`AgentSpec.extensionGate`). */
+export interface ExtensionGateSpec {
+    /** `false` turns the gate off: extensions' tools run without asking, as the model decides. */
+    enabled?: boolean;
+    /**
+     * Tools that always ask, even inside a batch the person approved, and never offer "always", by
+     * extension and short tool name (`{ canva: ["create-design"] }`): added to its manifest's `confirmTools`.
+     */
+    confirmTools?: Record<string, string[]>;
+    /** In autonomous mode, where no one can be asked: `"deny"` (the default) blocks those tools, `"allow"` runs them. */
+    autonomous?: "deny" | "allow";
+}
 /** Who an agent is, as told to its model (`AgentSpec.identity`). */
 export interface AgentIdentity {
     /** The agent's name, e.g. "padawan". */

package/dist/core/claudeAiConnectors.d.ts

@@ -0,0 +1,35 @@
+import { type Options } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * The claude.ai connectors an agent lets in (#70): the person's account's integrations (Canva,
+ * Notion…), which the kit keeps out by default (`disableClaudeAiConnectors`, ADR-018). The SDK
+ * lets them in all or none, and lets one out only by its name (`deniedMcpServers`); an allowlist
+ * would have to list every other server of the session exactly (confirmed empirically, CLI
+ * 2.1.300). So the kit asks the account which it has, when the session opens, and denies by name
+ * the ones the agent didn't choose; a gate blocks a call to any other (one added since).
+ *
+ * `toggleMcpServer()` is never used for them: it saves the switch in the person's own Claude Code
+ * config for the folder (`~/.claude.json`, `disabledMcpServers`), not only in the session
+ * (confirmed empirically, CLI 2.1.300).
+ */
+/** The name the SDK gives a claude.ai connector's server: `claude.ai <Name>`. */
+export declare const CONNECTOR_PREFIX = "claude.ai ";
+/** The prefix of a server's tools as the model names them: `claude.ai Claude Docs` → `mcp__claude_ai_Claude_Docs__`. */
+export declare function serverToolPrefix(server: string): string;
+/** Whether a tool is a claude.ai connector's. */
+export declare function isConnectorTool(tool: string): boolean;
+/** What the agent chose, set against what the account has: the servers to let in, to deny, and the names it asked for that aren't there. */
+export interface ConnectorChoice {
+    allowed: string[];
+    denied: string[];
+    missing: string[];
+}
+/** Chooses among the account's connectors (`found`, as the SDK names them) the ones the agent wants, by the name claude.ai shows (any case). */
+export declare function chooseConnectors(found: readonly string[], wanted: readonly string[]): ConnectorChoice;
+/**
+ * The account's claude.ai connectors, by the names the SDK gives them: a session that sends no
+ * message, opened in `cwd` with connectors on, its servers' status read and closed. A few seconds;
+ * an empty list when it can't tell (no login, no network), so nothing is let in.
+ */
+export declare function discoverConnectors(cwd: string, options?: Pick<Options, "pathToClaudeCodeExecutable" | "env"> & {
+    timeoutMs?: number;
+}): Promise<string[]>;

package/dist/core/claudeAiConnectors.js

@@ -0,0 +1,76 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * The claude.ai connectors an agent lets in (#70): the person's account's integrations (Canva,
+ * Notion…), which the kit keeps out by default (`disableClaudeAiConnectors`, ADR-018). The SDK
+ * lets them in all or none, and lets one out only by its name (`deniedMcpServers`); an allowlist
+ * would have to list every other server of the session exactly (confirmed empirically, CLI
+ * 2.1.300). So the kit asks the account which it has, when the session opens, and denies by name
+ * the ones the agent didn't choose; a gate blocks a call to any other (one added since).
+ *
+ * `toggleMcpServer()` is never used for them: it saves the switch in the person's own Claude Code
+ * config for the folder (`~/.claude.json`, `disabledMcpServers`), not only in the session
+ * (confirmed empirically, CLI 2.1.300).
+ */
+/** The name the SDK gives a claude.ai connector's server: `claude.ai <Name>`. */
+export const CONNECTOR_PREFIX = "claude.ai ";
+/** The prefix of a server's tools as the model names them: `claude.ai Claude Docs` → `mcp__claude_ai_Claude_Docs__`. */
+export function serverToolPrefix(server) {
+    return `mcp__${server.replace(/[^A-Za-z0-9_-]/g, "_")}__`;
+}
+/** Whether a tool is a claude.ai connector's. */
+export function isConnectorTool(tool) {
+    // `claude.ai <Name>` becomes `mcp__claude_ai_<Name>__`: the prefix up to the name.
+    return tool.startsWith("mcp__claude_ai_");
+}
+/** Chooses among the account's connectors (`found`, as the SDK names them) the ones the agent wants, by the name claude.ai shows (any case). */
+export function chooseConnectors(found, wanted) {
+    const label = (server) => (server.startsWith(CONNECTOR_PREFIX) ? server.slice(CONNECTOR_PREFIX.length) : server).toLowerCase();
+    const asked = new Set(wanted.map(label));
+    const allowed = found.filter((server) => asked.has(label(server)));
+    const present = new Set(allowed.map(label));
+    return { allowed, denied: found.filter((server) => !asked.has(label(server))), missing: wanted.filter((name) => !present.has(label(name))) };
+}
+/**
+ * The account's claude.ai connectors, by the names the SDK gives them: a session that sends no
+ * message, opened in `cwd` with connectors on, its servers' status read and closed. A few seconds;
+ * an empty list when it can't tell (no login, no network), so nothing is let in.
+ */
+export async function discoverConnectors(cwd, options = {}) {
+    let release = () => { };
+    const done = new Promise((resolve) => (release = resolve));
+    // A conversation that never sends a message, ended when the look is over: the session only starts its servers.
+    const prompt = { [Symbol.asyncIterator]: () => ({ next: () => done.then(() => ({ done: true, value: undefined })) }) };
+    const session = query({
+        prompt,
+        options: {
+            cwd,
+            settingSources: ["project"],
+            tools: [],
+            settings: { autoMemoryEnabled: false, disableClaudeAiConnectors: false },
+            ...(options.pathToClaudeCodeExecutable ? { pathToClaudeCodeExecutable: options.pathToClaudeCodeExecutable } : {}),
+            ...(options.env ? { env: options.env } : {}),
+        },
+    });
+    void (async () => {
+        for await (const message of session)
+            void message;
+    })().catch(() => undefined);
+    try {
+        const connectors = async () => (await session.mcpServerStatus()).filter((server) => server.scope === "claudeai" || server.name.startsWith(CONNECTOR_PREFIX));
+        // Connectors come from the account after the session starts: wait until none is pending.
+        const deadline = Date.now() + (options.timeoutMs ?? 10_000);
+        let found = await connectors().catch(() => []);
+        while (Date.now() < deadline && (!found.length || found.some((server) => server.status === "pending"))) {
+            await new Promise((resolve) => setTimeout(resolve, 400));
+            found = await connectors().catch(() => []);
+        }
+        return found.map((server) => server.name);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        release();
+        session.close();
+    }
+}

package/dist/core/extensions.d.ts

@@ -64,6 +64,13 @@ export interface ExtensionContribution {
      * no `readOnlyTools`. A list in the manifest wins: its servers aren't here.
      */
     readOnlyHintServers?: string[];
+    /**
+     * Its MCP tools that always ask the person in guided mode, even inside an approved batch, by full
+     * name (#76): an installed extension's manifest's `confirmTools`.
+     */
+    confirmTools?: string[];
+    /** Its MCP servers whose tools that always ask guided mode learns from their `destructiveHint`: an installed extension whose manifest lists no `confirmTools`. */
+    confirmHintServers?: string[];
     /**
      * Its MCP servers that are remote (#61), by session name: the SDK fixes their URL and headers
      * when the session opens, so a changed option takes opening it again, and they may need the

package/dist/core/externalExtensions.d.ts

@@ -101,6 +101,12 @@ export interface ExternalManifest {
      * list is the whole answer, even empty.
      */
     readOnlyTools?: string[];
+    /**
+     * Its tools that always ask the person in guided mode (short names), even inside a batch they
+     * approved, and never offer "always" (#76): what creates, edits or publishes in their account.
+     * Without the key, its servers' `destructiveHint` says which.
+     */
+    confirmTools?: string[];
     /** Its tools' chat labels, by short name (of any of its servers) and language (English when the kit's isn't there). */
     labels: Record<string, Partial<Record<Language, ExternalToolLabel>>>;
     /** What it says about itself in a session, for the agent to tell the person (`SessionFacts`). */
@@ -140,6 +146,8 @@ export interface LockEntry {
     options?: Record<string, OptionValue>;
     /** The npm packages its servers run with npx (#54), by `<package>@<version>`: in the agent's package cache, checked when it loads. */
     packages?: Record<string, CachedPackage>;
+    /** What the person said about its tools in guided mode (#74, #76): kept answers, or the gate off for it. */
+    confirm?: ExtensionConfirm;
     enabled: boolean;
     /** When it was installed, ISO 8601 in UTC. */
     installed: string;
@@ -264,6 +272,28 @@ export declare function removeExtension(scopeDir: string, name: string, options?
 }): Promise<boolean>;
 /** The size in bytes of the files under `dir` (0 when it doesn't exist). */
 export declare function folderSize(dir: string): Promise<number>;
+/** A kept answer to guided mode's question about one of an extension's tools (#76). */
+export type ToolConfirmation = "always" | "never";
+/** What the person said about an extension's tools in guided mode (#74, #76), in its lock. */
+export interface ExtensionConfirm {
+    /** Its tools run without asking: the person trusts it. */
+    off?: boolean;
+    /** Their kept answers, by the tool's short name. */
+    tools?: Record<string, ToolConfirmation>;
+}
+/**
+ * Changes what's kept about an installed extension's tools in guided mode: `off` turns the gate
+ * off (or back on) for it; `tool` keeps an answer for one tool (`undefined` asks again);
+ * `reset` forgets every kept answer. False when it isn't installed there.
+ */
+export declare function setExtensionConfirm(scopeDir: string, name: string, change: {
+    off?: boolean;
+    tool?: {
+        name: string;
+        answer: ToolConfirmation | undefined;
+    };
+    reset?: boolean;
+}): Promise<boolean>;
 /** Enables or disables an installed extension in a scope; false when it isn't there. */
 export declare function setExtensionEnabled(scopeDir: string, name: string, enabled: boolean): Promise<boolean>;
 /**

package/dist/core/externalExtensions.js

@@ -140,6 +140,7 @@ export async function readExternalManifest(dir) {
         requirements: parseRequirements(kit.requirements),
         servers: await pluginServers(dir, raw),
         ...(Array.isArray(kit.readOnlyTools) ? { readOnlyTools: kit.readOnlyTools.filter((tool) => typeof tool === "string") } : {}),
+        ...(Array.isArray(kit.confirmTools) ? { confirmTools: kit.confirmTools.filter((tool) => typeof tool === "string") } : {}),
         labels: kit.labels ?? {},
         ...(kit.help ? { help: kit.help } : {}),
         userConfig: parseUserConfig(raw.userConfig),
@@ -424,6 +425,10 @@ function externalExtension(installed, manifest, cache, unavailable = []) {
                 ...(manifest.readOnlyTools
                     ? { readOnlyTools: Object.keys(servers).flatMap((server) => manifest.readOnlyTools.map((tool) => `mcp__${server}__${tool}`)) }
                     : { readOnlyTools: [], readOnlyHintServers: Object.keys(servers) }),
+                // The same for what always asks in guided mode (#76): the list, or the servers' destructiveHint.
+                ...(manifest.confirmTools
+                    ? { confirmTools: Object.keys(servers).flatMap((server) => manifest.confirmTools.map((tool) => `mcp__${server}__${tool}`)) }
+                    : { confirmHintServers: Object.keys(servers) }),
                 toolLabels: manifestToolLabels(manifest, Object.keys(servers)),
                 ...(remote.length ? { remoteServers: remote } : {}),
                 ...(manifest.help ? { helpLines: [manifest.help] } : {}),
@@ -568,6 +573,9 @@ export async function addExtension(source, scopeDir, options = {}) {
         const kept = Object.fromEntries(Object.entries(lock[manifest.name]?.options ?? {}).filter(([key]) => manifest.userConfig[key] && !manifest.userConfig[key].sensitive));
         if (Object.keys(kept).length)
             locked.options = kept;
+        // And what the person said about its tools in guided mode (#76): theirs, not the version's.
+        if (lock[manifest.name]?.confirm)
+            locked.confirm = lock[manifest.name].confirm;
         await rm(target, { recursive: true, force: true });
         await mkdir(scopeDir, { recursive: true });
         const origin = options.origin ?? (isGitSource(source) ? source : from);
@@ -636,6 +644,35 @@ export async function folderSize(dir) {
     }
     return size;
 }
+/**
+ * Changes what's kept about an installed extension's tools in guided mode: `off` turns the gate
+ * off (or back on) for it; `tool` keeps an answer for one tool (`undefined` asks again);
+ * `reset` forgets every kept answer. False when it isn't installed there.
+ */
+export async function setExtensionConfirm(scopeDir, name, change) {
+    const lock = await readLock(scopeDir);
+    const entry = lock[name];
+    if (!entry)
+        return false;
+    const confirm = { ...entry.confirm, tools: change.reset ? {} : { ...entry.confirm?.tools } };
+    if (change.off !== undefined)
+        confirm.off = change.off;
+    if (change.tool) {
+        if (change.tool.answer)
+            confirm.tools[change.tool.name] = change.tool.answer;
+        else
+            delete confirm.tools[change.tool.name];
+    }
+    if (!confirm.off)
+        delete confirm.off;
+    if (!Object.keys(confirm.tools).length)
+        delete confirm.tools;
+    lock[name] = { ...entry, ...(Object.keys(confirm).length ? { confirm } : {}) };
+    if (!Object.keys(confirm).length)
+        delete lock[name].confirm;
+    await writeLock(scopeDir, lock);
+    return true;
+}
 /** Enables or disables an installed extension in a scope; false when it isn't there. */
 export async function setExtensionEnabled(scopeDir, name, enabled) {
     const lock = await readLock(scopeDir);

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

@@ -0,0 +1,57 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import type { Mode } from "../agentSpec.js";
+import type { ToolLabels } from "../toolLabels.js";
+/** An installed extension whose tools the guided gate watches. */
+export interface GuardedExtension {
+    name: string;
+    /** Its scope's folder: its lock keeps what the person said about its tools. */
+    scopeDir: string;
+    /** Its MCP servers, by session name. */
+    servers: readonly string[];
+    /** Its tools that always ask (full names): its manifest's `confirmTools` and the agent's own list. */
+    confirmTools: readonly string[];
+}
+/** One answer the gate gave, for the transcript: what was asked, and what the person (or the mode) said. */
+export interface GuidedDecision {
+    extension: string;
+    tool: string;
+    answer: "yes" | "session" | "always" | "no" | "never" | "kept-never" | "autonomous-deny";
+}
+/** The guided gate: its `PreToolUse` hook, and what ends or starts an approved batch. */
+export interface GuidedGate {
+    preToolUse: HookCallback;
+    /** A `UserPromptSubmit` hook: the person's next message ends an approved batch. */
+    userPromptSubmit: HookCallback;
+    /** `request_human_approval`'s answer: approved, the calls that follow don't ask until the person's next message. */
+    approvalAnswered(approved: boolean): void;
+}
+/**
+ * Guided mode's gate for installed extensions' tools that change things (#74, #76): ADR-025 treats
+ * every extension tool as publishing unless it's known to only read, and in guided mode the person
+ * says yes before one runs, whatever the model did first. The step gate covers interactive mode
+ * (it asks before everything) and the plan gate plan mode (it denies), so this one decides only in
+ * guided and autonomous mode, where no one can be asked and `autonomous` says what happens.
+ *
+ * Read-only tools (the manifest's `readOnlyTools`, else the server's `readOnlyHint`) never ask.
+ * The rest ask through the interaction port, with answers the person can make last: this call,
+ * this session, always (kept in the extension's lock), no, never (kept too). Right after
+ * `request_human_approval` is approved, calls go on until the person's next message (a batch),
+ * except those that always ask: the agent's or the manifest's `confirmTools`, else the server's
+ * `destructiveHint`, which aren't offered "always" either. An extension whose lock says `off`
+ * runs without asking. Approving gives no decision of its own, so the other gates still judge.
+ */
+export declare function createGuidedGate(options: {
+    runDir: string;
+    mode: () => Mode;
+    extensions: readonly GuardedExtension[];
+    /** Whether a tool only reads: the extensions' `readOnlyTools`, else their servers' hints. */
+    isReadOnly(tool: string): Promise<boolean>;
+    /** Whether a tool's server marks it `destructiveHint`, for those whose manifest lists no `confirmTools`. */
+    isDestructive(tool: string): Promise<boolean>;
+    /** In autonomous mode, where no one can be asked: denied (the default) or run. */
+    autonomous?: "deny" | "allow";
+    /** The tools' labels in the session's language, to say what's about to happen. */
+    labels?: () => ToolLabels;
+    /** Each answer, for the transcript. */
+    record?(decision: GuidedDecision): Promise<void>;
+}): GuidedGate;

package/dist/core/hooks/guidedGate.js

@@ -0,0 +1,97 @@
+import { askForChoice } from "./humanInput.js";
+import { readLock, setExtensionConfirm } from "../externalExtensions.js";
+import { t } from "../messages/index.js";
+/** The kit's approval tool: asking it ends a batch, and its yes starts one. */
+const APPROVAL_TOOL = "mcp__approvals__request_human_approval";
+/**
+ * Guided mode's gate for installed extensions' tools that change things (#74, #76): ADR-025 treats
+ * every extension tool as publishing unless it's known to only read, and in guided mode the person
+ * says yes before one runs, whatever the model did first. The step gate covers interactive mode
+ * (it asks before everything) and the plan gate plan mode (it denies), so this one decides only in
+ * guided and autonomous mode, where no one can be asked and `autonomous` says what happens.
+ *
+ * Read-only tools (the manifest's `readOnlyTools`, else the server's `readOnlyHint`) never ask.
+ * The rest ask through the interaction port, with answers the person can make last: this call,
+ * this session, always (kept in the extension's lock), no, never (kept too). Right after
+ * `request_human_approval` is approved, calls go on until the person's next message (a batch),
+ * except those that always ask: the agent's or the manifest's `confirmTools`, else the server's
+ * `destructiveHint`, which aren't offered "always" either. An extension whose lock says `off`
+ * runs without asking. Approving gives no decision of its own, so the other gates still judge.
+ */
+export function createGuidedGate(options) {
+    const thisSession = new Set();
+    let batch = false;
+    const deny = (input, reason) => ({ hookSpecificOutput: { hookEventName: input.hook_event_name, permissionDecision: "deny", permissionDecisionReason: reason } });
+    const preToolUse = async (input) => {
+        const pre = input;
+        const full = pre.tool_name;
+        // A new approval request ends the batch the last one started, whatever its answer.
+        if (full === APPROVAL_TOOL)
+            batch = false;
+        const mode = options.mode();
+        if (mode !== "guided" && mode !== "autonomous")
+            return {};
+        const server = options.extensions.flatMap((extension) => extension.servers.map((name) => ({ extension, prefix: `mcp__${name}__` }))).find(({ prefix }) => full.startsWith(prefix));
+        if (!server)
+            return {};
+        const { extension } = server;
+        const tool = full.slice(server.prefix.length);
+        if (await options.isReadOnly(full))
+            return {};
+        const confirm = (await readLock(extension.scopeDir).catch(() => ({})))[extension.name]?.confirm;
+        if (confirm?.off)
+            return {};
+        const record = async (answer) => await options.record?.({ extension: extension.name, tool: full, answer }).catch(() => { });
+        const kept = confirm?.tools?.[tool];
+        if (kept === "never") {
+            await record("kept-never");
+            return deny(pre, `The person never lets ${extension.name} run ${tool} (they said so before). Don't call it again: do the task another way, or tell them it needs it.`);
+        }
+        const alwaysAsks = extension.confirmTools.includes(full) || (await options.isDestructive(full));
+        if (kept === "always" && !alwaysAsks)
+            return {};
+        if (thisSession.has(full))
+            return {};
+        if (mode === "autonomous") {
+            if (options.autonomous === "allow")
+                return {};
+            await record("autonomous-deny");
+            return deny(pre, `Autonomous mode: no one can approve ${extension.name}'s ${tool}, which changes things, so it isn't run. Do what you can without it, and say it needs a person to approve it.`);
+        }
+        if (batch && !alwaysAsks)
+            return {};
+        const answers = t().confirmAnswers;
+        const choices = [answers.yes, answers.session, ...(alwaysAsks ? [] : [answers.always]), answers.no, answers.never];
+        const label = options.labels?.()[full]?.label((pre.tool_input ?? {}));
+        const answer = await askForChoice(options.runDir, {
+            title: t().guidedTitle(extension.name),
+            lines: [...(label ? [label] : []), t().toolLine(full), t().parametersLine(JSON.stringify(pre.tool_input, null, 2))],
+        }, choices);
+        const picked = answer.chosen[0];
+        if (picked === answers.yes || picked === answers.session || picked === answers.always) {
+            if (picked === answers.session)
+                thisSession.add(full);
+            if (picked === answers.always)
+                await setExtensionConfirm(extension.scopeDir, extension.name, { tool: { name: tool, answer: "always" } });
+            await record(picked === answers.yes ? "yes" : picked === answers.session ? "session" : "always");
+            return {};
+        }
+        if (picked === answers.never) {
+            await setExtensionConfirm(extension.scopeDir, extension.name, { tool: { name: tool, answer: "never" } });
+            await record("never");
+            return deny(pre, `The person never lets ${extension.name} run ${tool}. Don't call it again: do the task another way, or tell them it needs it.`);
+        }
+        await record("no");
+        return deny(pre, `The person didn't approve this call${answer.other ? `. They said: ${answer.other}` : ""}. Don't retry it without asking them first.`);
+    };
+    return {
+        preToolUse,
+        userPromptSubmit: async () => {
+            batch = false;
+            return {};
+        },
+        approvalAnswered(approved) {
+            batch = approved;
+        },
+    };
+}

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

@@ -0,0 +1,22 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+/** What a call to a remote MCP server does (#70): goes on, asks the person first, or is blocked. */
+export type RemoteServersPolicy = "allow" | "ask" | "deny";
+/**
+ * PreToolUse hook for remote MCP servers (#70): what the model sends one leaves the computer.
+ * - A claude.ai connector's tool the agent didn't choose is always blocked: a connector the
+ *   account gained after the session opened, which the session's denylist doesn't name.
+ * - A remote server's tool (an installed extension's, the agent's own, a chosen connector) goes
+ *   on with `allow`; with `ask`, the person approves each call, told where it goes (blocked when
+ *   no one can be asked); with `deny`, it's blocked.
+ * Approving gives no decision of its own, so the other gates (plan mode, the file scope) still judge.
+ */
+export declare function createRemoteGate(options: {
+    runDir: string;
+    policy: RemoteServersPolicy;
+    /** Where a tool's call goes (a host, a connector), or nothing when it isn't remote. */
+    destination: (tool: string) => string | undefined;
+    /** The chosen connectors' tool prefixes (`serverToolPrefix()`). */
+    allowedConnectors: readonly string[];
+    /** Whether a person can be asked now (not autonomous). */
+    canAsk: () => boolean;
+}): HookCallback;

package/dist/core/hooks/remoteGate.js

@@ -0,0 +1,35 @@
+import { askForDecision } from "./humanInput.js";
+import { isConnectorTool } from "../claudeAiConnectors.js";
+import { t } from "../messages/index.js";
+/**
+ * PreToolUse hook for remote MCP servers (#70): what the model sends one leaves the computer.
+ * - A claude.ai connector's tool the agent didn't choose is always blocked: a connector the
+ *   account gained after the session opened, which the session's denylist doesn't name.
+ * - A remote server's tool (an installed extension's, the agent's own, a chosen connector) goes
+ *   on with `allow`; with `ask`, the person approves each call, told where it goes (blocked when
+ *   no one can be asked); with `deny`, it's blocked.
+ * Approving gives no decision of its own, so the other gates (plan mode, the file scope) still judge.
+ */
+export function createRemoteGate(options) {
+    const deny = (input, reason) => ({ hookSpecificOutput: { hookEventName: input.hook_event_name, permissionDecision: "deny", permissionDecisionReason: reason } });
+    return async (input) => {
+        const pre = input;
+        const tool = pre.tool_name;
+        if (isConnectorTool(tool) && !options.allowedConnectors.some((prefix) => tool.startsWith(prefix))) {
+            return deny(pre, "This agent doesn't use that claude.ai connector: it isn't one of the connectors it lets in. Don't call it again.");
+        }
+        const destination = options.destination(tool);
+        if (!destination || options.policy === "allow")
+            return {};
+        if (options.policy === "deny" || !options.canAsk()) {
+            return deny(pre, `This agent sends nothing to remote servers here: calling ${destination} isn't allowed. Do the task without it, or tell the person it needs that service.`);
+        }
+        const answer = await askForDecision(options.runDir, {
+            title: t().remoteCallTitle(destination),
+            lines: [t().toolLine(tool), t().parametersLine(JSON.stringify(pre.tool_input, null, 2))],
+        });
+        if (answer === "" || answer === "y" || answer === "yes")
+            return {};
+        return deny(pre, `The person didn't let this call go to ${destination}.`);
+    };
+}

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

@@ -3,6 +3,8 @@ import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
 export interface TranscriptLogger {
     preToolUse: HookCallback;
     postToolUse: HookCallback;
+    /** Another event the kit keeps in it (a gate's answer, #74): one line, with its time. */
+    note(event: string, entry: Record<string, unknown>): Promise<void>;
 }
 /**
  * Logs every tool call (request + result) as one JSON line, redacting `secrets` (e.g. a

package/dist/core/hooks/transcriptLogger.js

@@ -39,7 +39,7 @@ export function createTranscriptLogger(transcriptPath, secrets = []) {
         });
         return {};
     };
-    return { preToolUse, postToolUse };
+    return { preToolUse, postToolUse, note: async (event, entry) => await write({ ts: new Date().toISOString(), event, ...entry }) };
 }
 /** Avoids bloating the transcript with large payloads (browser-tool screenshots/base64). */
 export function summarizeToolResponse(response) {