@falkenslab/agent-kit 0.26.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)

package/dist/core/agentSpec.d.ts

@@ -186,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()`
@@ -209,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/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/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) {

package/dist/core/messages/de.js

@@ -35,7 +35,7 @@ export const de = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "aktiviert" : "deaktiviert"}, in derselben Sitzung)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "aktiviert" : "deaktiviert"}: die Sitzung wird mit derselben Unterhaltung neu geöffnet)`,
     extensionNotInstalled: (name) => `(${name} ist nicht installiert: /extensions listet sie auf)`,
-    extensionsUsage: "(Verwendung: /extensions, enable|disable <Name>, config <Name> [Schlüssel=Wert…], search [Wörter], install <Name>, update [Name], remove <Name> [--delete-data], reload, trust, sign-in <Name> [Rückruf-URL], sign-out <Name>)",
+    extensionsUsage: "(Verwendung: /extensions, enable|disable <Name>, config <Name> [Schlüssel=Wert… | confirm=on|off|reset], search [Wörter], install <Name>, update [Name], remove <Name> [--delete-data], reload, trust, sign-in <Name> [Rückruf-URL], sign-out <Name>)",
     extensionsCantReopen: "(dieser Chat kann seine Sitzung nicht neu öffnen: im Terminal aktivieren oder deaktivieren und neu starten)",
     extensionOptions: (name) => `Optionen von ${name}:`,
     extensionNoOptions: (name) => `(${name} hat keine Optionen)`,
@@ -61,6 +61,12 @@ export const de = {
     extensionSignInUnavailable: (name) => `(bei ${name} kann man sich hier nicht anmelden: sie läuft nicht in dieser Sitzung, hat keinen entfernten Server, oder das SDK dieses Agenten kann es nicht)`,
     extensionSignedOut: (name) => `(bei ${name} abgemeldet: sie bittet dich, dich erneut anzumelden)`,
     remoteCallTitle: (destination) => `Das an ${destination} senden? Es verlässt diesen Computer`,
+    guidedTitle: (extension) => `${extension} das tun lassen?`,
+    confirmAnswers: { yes: "Ja", session: "Ja, für diese Sitzung", always: "Ja, immer", no: "Nein", never: "Nein, nie" },
+    extensionConfirmOn: (name) => `Im geführten Modus fragen die Werkzeuge von ${name}, die etwas ändern, zuerst (confirm=off führt sie ohne Nachfrage aus):`,
+    extensionConfirmOff: (name) => `Im geführten Modus laufen die Werkzeuge von ${name} ohne Nachfrage (confirm=on fragt wieder).`,
+    confirmKept: (tool, answer) => `  ${tool}: ${answer === "always" ? "immer ja" : "nie"}`,
+    confirmNoneKept: "  (keine gespeicherten Antworten; confirm=reset vergisst sie)",
     connectorsAllowed: (names) => `claude.ai-Connectoren: ${names}`,
     connectorsMissing: (names) => `Nicht in deinem claude.ai-Konto: ${names} (verbinde ihn auf claude.ai und öffne die Sitzung neu)`,
     extensionInstalled: (name) => `(${name} installiert: in einem neuen Gespräch da, oder sofort mit /extensions reload, ohne dieses zu verlieren)`,

package/dist/core/messages/en.d.ts

@@ -84,6 +84,22 @@ export interface Messages {
     extensionSignedOut(name: string): string;
     /** Before a call to a remote MCP server, when the agent asks first (#70): where it goes. */
     remoteCallTitle(destination: string): string;
+    /** Guided mode's question before an installed extension's tool that changes things (#74): its title. */
+    guidedTitle(extension: string): string;
+    /** Its answers (#76): this call, this session, always, no, never. */
+    confirmAnswers: {
+        yes: string;
+        session: string;
+        always: string;
+        no: string;
+        never: string;
+    };
+    /** In /extensions config: whether its tools ask in guided mode, before the answers kept. */
+    extensionConfirmOn(name: string): string;
+    extensionConfirmOff(name: string): string;
+    /** A kept answer about one of its tools. */
+    confirmKept(tool: string, answer: "always" | "never"): string;
+    confirmNoneKept: string;
     /** In /extensions: the claude.ai connectors let in (#70). */
     connectorsAllowed(names: string): string;
     /** In /extensions: connectors the agent asked for that the account hasn't. */

package/dist/core/messages/en.js

@@ -34,7 +34,7 @@ export const en = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "enabled" : "disabled"}, in this same session)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "enabled" : "disabled"}: the session reopens, with the same conversation)`,
     extensionNotInstalled: (name) => `(${name} isn't installed: /extensions lists them)`,
-    extensionsUsage: "(usage: /extensions, enable|disable <name>, config <name> [key=value…], search [words], install <name>, update [name], remove <name> [--delete-data], reload, trust, sign-in <name> [callback URL], sign-out <name>)",
+    extensionsUsage: "(usage: /extensions, enable|disable <name>, config <name> [key=value… | confirm=on|off|reset], search [words], install <name>, update [name], remove <name> [--delete-data], reload, trust, sign-in <name> [callback URL], sign-out <name>)",
     extensionsCantReopen: "(this chat can't reopen its session: enable or disable it from the terminal, and start again)",
     extensionOptions: (name) => `${name}'s options:`,
     extensionNoOptions: (name) => `(${name} has no options)`,
@@ -61,6 +61,12 @@ export const en = {
     extensionSignInUnavailable: (name) => `(${name} can't be signed in to here: it isn't running in this session, has no remote server, or this agent's SDK can't sign in)`,
     extensionSignedOut: (name) => `(signed out of ${name}: it will ask you to sign in again)`,
     remoteCallTitle: (destination) => `Send this to ${destination}? It leaves this computer`,
+    guidedTitle: (extension) => `Let ${extension} do this?`,
+    confirmAnswers: { yes: "Yes", session: "Yes, for this session", always: "Yes, always", no: "No", never: "No, never" },
+    extensionConfirmOn: (name) => `In guided mode, ${name}'s tools that change things ask first (confirm=off runs them without asking):`,
+    extensionConfirmOff: (name) => `In guided mode, ${name}'s tools run without asking (confirm=on asks again).`,
+    confirmKept: (tool, answer) => `  ${tool}: ${answer === "always" ? "always yes" : "never"}`,
+    confirmNoneKept: "  (no kept answers; confirm=reset forgets them)",
     connectorsAllowed: (names) => `claude.ai connectors: ${names}`,
     connectorsMissing: (names) => `Not in your claude.ai account: ${names} (connect it on claude.ai, then reopen the session)`,
     extensionUpdated: (name, from, to) => `(${name} updated, ${from} → ${to}: it's there in a new conversation, or now with /extensions reload)`,

package/dist/core/messages/es.js

@@ -35,7 +35,7 @@ export const es = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "activada" : "desactivada"}, en esta misma sesión)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "activada" : "desactivada"}: la sesión se reabre, con la misma conversación)`,
     extensionNotInstalled: (name) => `(${name} no está instalada: /extensions las lista)`,
-    extensionsUsage: "(uso: /extensions, enable|disable <nombre>, config <nombre> [clave=valor…], search [palabras], install <nombre>, update [nombre], remove <nombre> [--delete-data], reload, trust, sign-in <nombre> [URL de vuelta], sign-out <nombre>)",
+    extensionsUsage: "(uso: /extensions, enable|disable <nombre>, config <nombre> [clave=valor… | confirm=on|off|reset], search [palabras], install <nombre>, update [nombre], remove <nombre> [--delete-data], reload, trust, sign-in <nombre> [URL de vuelta], sign-out <nombre>)",
     extensionsCantReopen: "(este chat no puede reabrir su sesión: actívala o desactívala desde la terminal y vuelve a empezar)",
     extensionOptions: (name) => `Opciones de ${name}:`,
     extensionNoOptions: (name) => `(${name} no tiene opciones)`,
@@ -61,6 +61,12 @@ export const es = {
     extensionSignInUnavailable: (name) => `(no se puede iniciar sesión en ${name} aquí: no se ejecuta en esta sesión, no tiene servidor remoto, o el SDK de este agente no sabe hacerlo)`,
     extensionSignedOut: (name) => `(sesión cerrada en ${name}: te pedirá que vuelvas a iniciarla)`,
     remoteCallTitle: (destination) => `¿Enviar esto a ${destination}? Sale de este ordenador`,
+    guidedTitle: (extension) => `¿Dejas que ${extension} haga esto?`,
+    confirmAnswers: { yes: "Sí", session: "Sí, en esta sesión", always: "Sí, siempre", no: "No", never: "No, nunca" },
+    extensionConfirmOn: (name) => `En modo guiado, las herramientas de ${name} que cambian cosas preguntan antes (confirm=off las ejecuta sin preguntar):`,
+    extensionConfirmOff: (name) => `En modo guiado, las herramientas de ${name} se ejecutan sin preguntar (confirm=on vuelve a preguntar).`,
+    confirmKept: (tool, answer) => `  ${tool}: ${answer === "always" ? "siempre sí" : "nunca"}`,
+    confirmNoneKept: "  (ninguna respuesta guardada; confirm=reset las olvida)",
     connectorsAllowed: (names) => `Conectores de claude.ai: ${names}`,
     connectorsMissing: (names) => `No están en tu cuenta de claude.ai: ${names} (conéctalo en claude.ai y vuelve a abrir la sesión)`,
     extensionInstalled: (name) => `(${name} instalada: está en una conversación nueva, o ya con /extensions reload, sin perder esta)`,

package/dist/core/messages/fr.js

@@ -35,7 +35,7 @@ export const fr = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"}, dans cette même session)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"} : la session se rouvre, avec la même conversation)`,
     extensionNotInstalled: (name) => `(${name} n'est pas installée : /extensions les liste)`,
-    extensionsUsage: "(usage : /extensions, enable|disable <nom>, config <nom> [clé=valeur…], search [mots], install <nom>, update [nom], remove <nom> [--delete-data], reload, trust, sign-in <nom> [URL de retour], sign-out <nom>)",
+    extensionsUsage: "(usage : /extensions, enable|disable <nom>, config <nom> [clé=valeur… | confirm=on|off|reset], search [mots], install <nom>, update [nom], remove <nom> [--delete-data], reload, trust, sign-in <nom> [URL de retour], sign-out <nom>)",
     extensionsCantReopen: "(ce chat ne peut pas rouvrir sa session : activez-la ou désactivez-la depuis le terminal, puis recommencez)",
     extensionOptions: (name) => `Options de ${name} :`,
     extensionNoOptions: (name) => `(${name} n'a pas d'options)`,
@@ -61,6 +61,12 @@ export const fr = {
     extensionSignInUnavailable: (name) => `(impossible de se connecter à ${name} ici : elle ne tourne pas dans cette session, n'a pas de serveur distant, ou le SDK de cet agent ne sait pas le faire)`,
     extensionSignedOut: (name) => `(déconnecté de ${name} : elle vous demandera de vous reconnecter)`,
     remoteCallTitle: (destination) => `Envoyer ceci à ${destination} ? Cela quitte cet ordinateur`,
+    guidedTitle: (extension) => `Laisser ${extension} faire ceci ?`,
+    confirmAnswers: { yes: "Oui", session: "Oui, pour cette session", always: "Oui, toujours", no: "Non", never: "Non, jamais" },
+    extensionConfirmOn: (name) => `En mode guidé, les outils de ${name} qui modifient des choses demandent d'abord (confirm=off les exécute sans demander) :`,
+    extensionConfirmOff: (name) => `En mode guidé, les outils de ${name} s'exécutent sans demander (confirm=on demande à nouveau).`,
+    confirmKept: (tool, answer) => `  ${tool} : ${answer === "always" ? "toujours oui" : "jamais"}`,
+    confirmNoneKept: "  (aucune réponse gardée ; confirm=reset les oublie)",
     connectorsAllowed: (names) => `Connecteurs claude.ai : ${names}`,
     connectorsMissing: (names) => `Absents de votre compte claude.ai : ${names} (connectez-le sur claude.ai, puis rouvrez la session)`,
     extensionInstalled: (name) => `(${name} installée : elle est là dans une nouvelle conversation, ou dès maintenant avec /extensions reload, en gardant celle-ci)`,

package/dist/core/readOnlyHints.d.ts

@@ -1,13 +1,19 @@
 import type { McpServerStatus } from "@anthropic-ai/claude-agent-sdk";
+/** What an MCP tool's own server says about it: `readOnlyHint`, `destructiveHint`. */
+export type ToolHint = "readOnly" | "destructive";
 /**
- * Plan mode's read-only tools from the MCP servers themselves (#53): for an installed extension
- * whose manifest lists no `readOnlyTools`, a tool its server marks `readOnlyHint` only reads.
+ * What the MCP servers themselves say about their tools (#53, #76): for an installed extension
+ * whose manifest lists no `readOnlyTools` (plan mode, guided mode) or no `confirmTools` (guided
+ * mode), a tool its server marks `readOnlyHint` only reads, and one it marks `destructiveHint`
+ * always asks.
  *
- * Asked when plan mode meets the call, not once at start: a server is `pending` for seconds after
+ * Asked when a gate meets the call, not once at start: a server is `pending` for seconds after
  * the session starts, and one turned off and on again (liveExtensions.ts) may come back with
  * other tools. The SDK's `mcpServerStatus()` gives each connected server's tools with
- * `annotations.readOnly`, set exactly when the server says `readOnlyHint: true` (confirmed
- * empirically: `readOnlyHint: false` and no hint both leave it out; the names are the short ones).
- * Anything else — not connected, not asked in time, no hint — is no: plan mode denies.
+ * `annotations.readOnly` (and `destructive`), set exactly when the server says the hint is `true`
+ * (confirmed empirically for `readOnlyHint`: `false` and no hint both leave it out; the names are
+ * the short ones). Anything else — not connected, not asked in time, no hint — is no.
  */
+export declare function createToolHints(servers: readonly string[], status: () => (() => Promise<McpServerStatus[]>) | undefined, hint: ToolHint): (toolName: string) => Promise<boolean>;
+/** Plan mode's read-only tools from the servers themselves: `createToolHints()` for `readOnlyHint`. */
 export declare function createReadOnlyHints(servers: readonly string[], status: () => (() => Promise<McpServerStatus[]>) | undefined): (toolName: string) => Promise<boolean>;

package/dist/core/readOnlyHints.js

@@ -1,15 +1,17 @@
 /**
- * Plan mode's read-only tools from the MCP servers themselves (#53): for an installed extension
- * whose manifest lists no `readOnlyTools`, a tool its server marks `readOnlyHint` only reads.
+ * What the MCP servers themselves say about their tools (#53, #76): for an installed extension
+ * whose manifest lists no `readOnlyTools` (plan mode, guided mode) or no `confirmTools` (guided
+ * mode), a tool its server marks `readOnlyHint` only reads, and one it marks `destructiveHint`
+ * always asks.
  *
- * Asked when plan mode meets the call, not once at start: a server is `pending` for seconds after
+ * Asked when a gate meets the call, not once at start: a server is `pending` for seconds after
  * the session starts, and one turned off and on again (liveExtensions.ts) may come back with
  * other tools. The SDK's `mcpServerStatus()` gives each connected server's tools with
- * `annotations.readOnly`, set exactly when the server says `readOnlyHint: true` (confirmed
- * empirically: `readOnlyHint: false` and no hint both leave it out; the names are the short ones).
- * Anything else — not connected, not asked in time, no hint — is no: plan mode denies.
+ * `annotations.readOnly` (and `destructive`), set exactly when the server says the hint is `true`
+ * (confirmed empirically for `readOnlyHint`: `false` and no hint both leave it out; the names are
+ * the short ones). Anything else — not connected, not asked in time, no hint — is no.
  */
-export function createReadOnlyHints(servers, status) {
+export function createToolHints(servers, status, hint) {
     return async (toolName) => {
         const server = servers.find((name) => toolName.startsWith(`mcp__${name}__`));
         const read = status();
@@ -18,9 +20,13 @@ export function createReadOnlyHints(servers, status) {
         const tool = toolName.slice(`mcp__${server}__`.length);
         const statuses = await within(read(), []);
         const found = statuses.find((entry) => entry.name === server && entry.status === "connected");
-        return found?.tools?.some((entry) => entry.name === tool && entry.annotations?.readOnly === true) ?? false;
+        return found?.tools?.some((entry) => entry.name === tool && entry.annotations?.[hint] === true) ?? false;
     };
 }
+/** Plan mode's read-only tools from the servers themselves: `createToolHints()` for `readOnlyHint`. */
+export function createReadOnlyHints(servers, status) {
+    return createToolHints(servers, status, "readOnly");
+}
 // A call to the session made from a hook, before a tool runs: never let it hold the tool up.
 const TIMEOUT_MS = 3000;
 const within = (promise, fallback) => Promise.race([promise.catch(() => fallback), new Promise((resolve) => setTimeout(() => resolve(fallback), TIMEOUT_MS).unref())]);

package/dist/core/session.js

@@ -9,6 +9,7 @@ import { createSubagentForegroundGate } from "./hooks/subagentForegroundGate.js"
 import { createFileScopeGate } from "./hooks/fileScopeGate.js";
 import { createPlanGate } from "./hooks/planGate.js";
 import { createRemoteGate } from "./hooks/remoteGate.js";
+import { createGuidedGate } from "./hooks/guidedGate.js";
 import { chooseConnectors, discoverConnectors, serverToolPrefix } from "./claudeAiConnectors.js";
 import { createHumanApprovalServer } from "./tools/humanApproval.js";
 import { createManualLoginServer } from "./tools/manualLogin.js";
@@ -19,7 +20,7 @@ import { aboutExtension, describeCapability, extensionsPromptSection, resolveExt
 import { allowAnyMcpTool } from "./mcpPermissions.js";
 import { pluginAgents } from "./pluginAgents.js";
 import { outsideArchive, unpackedClaudeExecutable } from "./packaged.js";
-import { listInstalled, loadExternalExtensions, scopePrivateDir } from "./externalExtensions.js";
+import { listInstalled, loadExternalExtensions, readLock, scopePrivateDir } from "./externalExtensions.js";
 import { replyLanguageInstruction } from "./language.js";
 import { chooseLanguage } from "./messages/index.js";
 import { createRunStore } from "./runs.js";
@@ -27,7 +28,7 @@ import { createSessionView, registerSessionView } from "./sessionFacts.js";
 import { createExtensionAuth, createExtensionRestart, createExtensionSwitch, mountPlugin } from "./liveExtensions.js";
 import { secretsDir } from "./extensionOptions.js";
 import { createElicitationHandler } from "./elicitation.js";
-import { createReadOnlyHints } from "./readOnlyHints.js";
+import { createReadOnlyHints, createToolHints } from "./readOnlyHints.js";
 import { agentKitVersion } from "./version.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
@@ -181,6 +182,28 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     const readOnlyTools = fromExtensions((contribution) => contribution.readOnlyTools);
     // Those whose manifest lists none: their servers say, asked while the session runs (#53).
     const readOnlyHintServers = fromExtensions((contribution) => contribution.readOnlyHintServers);
+    const readOnlyHinted = readOnlyHintServers.length ? createReadOnlyHints(readOnlyHintServers, () => late.view?.controls().mcpServerStatus) : undefined;
+    // Guided mode's gate for the installed extensions' tools that change things (#74, #76): whose
+    // they are, which always ask (the manifest's list and the agent's, else the servers' hints),
+    // and those the person said never to, kept in the lock: out of the session altogether.
+    const gateSpec = spec.extensionGate ?? {};
+    const guardedExtensions = gateSpec.enabled === false
+        ? []
+        : resolved.active.flatMap(({ extension }, index) => {
+            const installed = installedDirs.get(extension.name);
+            if (!installed)
+                return [];
+            const servers = Object.keys(added[index]?.mcpServers ?? {});
+            const own = (gateSpec.confirmTools?.[extension.name] ?? []).flatMap((tool) => servers.map((server) => `mcp__${server}__${tool}`));
+            return [{ name: extension.name, scopeDir: installed.scopeDir, servers, confirmTools: [...(added[index]?.confirmTools ?? []), ...own] }];
+        });
+    const neverTools = (await Promise.all(guardedExtensions.map(async (extension) => {
+        const confirm = (await readLock(extension.scopeDir).catch(() => ({})))[extension.name]?.confirm;
+        if (confirm?.off)
+            return [];
+        const never = Object.entries(confirm?.tools ?? {}).filter(([, answer]) => answer === "never");
+        return never.flatMap(([tool]) => extension.servers.map((server) => `mcp__${server}__${tool}`));
+    }))).flat();
     // What no file tool may touch: the agent's denied paths and the SDK's own credentials.
     // And the installed extensions' sensitive option values (#55), in each scope's .secrets/.
     const deniedPaths = [
@@ -193,6 +216,19 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     ];
     const transcriptPath = path.join(runDir, "transcript.jsonl");
     const transcriptLogger = createTranscriptLogger(transcriptPath, config.secrets ?? []);
+    const guidedGate = guardedExtensions.length
+        ? createGuidedGate({
+            runDir,
+            mode: () => modeControl.mode,
+            extensions: guardedExtensions,
+            isReadOnly: async (tool) => readOnlyTools.includes(tool) || ((await readOnlyHinted?.(tool)) ?? false),
+            isDestructive: createToolHints(fromExtensions((contribution) => contribution.confirmHintServers), () => late.view?.controls().mcpServerStatus, "destructive"),
+            ...(gateSpec.autonomous ? { autonomous: gateSpec.autonomous } : {}),
+            // The session's labels, built below: read when a call is asked about.
+            labels: () => toolLabels,
+            record: (decision) => transcriptLogger.note("guided_decision", { ...decision }),
+        })
+        : undefined;
     const promptSections = [
         spec.buildSystemPrompt(config),
         // What's on and what isn't, then the extensions' own sections.
@@ -255,7 +291,8 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         // mcpPermissions.ts for why a fixed allowedTools wildcard can't cover a server whose
         // name isn't known ahead of time.
         canUseTool: allowAnyMcpTool,
-        disallowedTools: spec.disallowedTools ?? [],
+        // And the extensions' tools the person said never to (#76).
+        disallowedTools: [...(spec.disallowedTools ?? []), ...neverTools],
         // TodoWrite (todos.ts) only exists with CLAUDE_CODE_ENABLE_TASKS=0: by default the CLI
         // offers its TaskCreate/TaskUpdate/TaskList/TaskGet tools instead, and drops TodoWrite from
         // the session even when `tools` names it (confirmed empirically). `env` replaces the
@@ -288,7 +325,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         ...(subagentDefinitions ? { agents: subagentDefinitions } : {}),
         mcpServers: {
             ...spec.buildMcpServers(config, runDir),
-            ...(includeApprovalTool ? { approvals: createHumanApprovalServer(runDir, spec.humanApprovalTexts, { modeControl }) } : {}),
+            ...(includeApprovalTool ? { approvals: createHumanApprovalServer(runDir, spec.humanApprovalTexts, { modeControl, ...(guidedGate ? { onApproval: guidedGate.approvalAnswered } : {}) }) } : {}),
             ...(manualInterventionTexts ? { manualLogin: createManualLoginServer(runDir, manualInterventionTexts) } : {}),
             // The extensions' tools (the knowledge base's, the sources').
             ...Object.assign({}, ...added.map((contribution) => contribution.mcpServers ?? {})),
@@ -313,6 +350,8 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                         }),
                     ],
                 },
+                // Guided mode asks before an installed extension's tool that changes things (#74, #76).
+                ...(guidedGate ? [{ hooks: [guidedGate.preToolUse] }] : []),
                 ...(fileTools.length || toolOnlyDirs.length
                     ? [{ hooks: [createFileScopeGate({
                                     projectDir: config.projectDir,
@@ -344,7 +383,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                                 createPlanGate({
                                     projectDir: config.projectDir,
                                     readOnlyTools,
-                                    ...(readOnlyHintServers.length ? { isReadOnlyHinted: createReadOnlyHints(readOnlyHintServers, () => late.view?.controls().mcpServerStatus) } : {}),
+                                    ...(readOnlyHinted ? { isReadOnlyHinted: readOnlyHinted } : {}),
                                     ...(spec.planMode?.isPlanFile ? { isPlanFile: (filePath) => spec.planMode.isPlanFile(filePath, config) } : {}),
                                     ...(spec.planMode?.isReadOnlyTool ? { isReadOnlyTool: spec.planMode.isReadOnlyTool } : {}),
                                 }, () => modeControl.mode === "plan"),
@@ -361,6 +400,8 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                     : []),
             ],
             PostToolUse: [{ hooks: [transcriptLogger.postToolUse] }],
+            // The person's message ends a batch they approved (guided mode, #74).
+            ...(guidedGate ? { UserPromptSubmit: [{ hooks: [guidedGate.userPromptSubmit] }] } : {}),
         },
     };
     // Where each remote server's calls go (#70), for the remote gate: an http/sse server's host

package/dist/core/tools/humanApproval.d.ts

@@ -10,10 +10,12 @@ export declare const DEFAULT_HUMAN_APPROVAL_TEXTS: HumanApprovalTexts;
 /**
  * The tools that ask the person, in every mode but autonomous: `request_human_approval`
  * (right before an action that publishes something visible to others and that's hard to
- * undo), `ask_human` (a choice between options, in a panel, within the turn) and, when the
+ * undo; approved, guided mode lets the calls that follow through until the person's next
+ * message, see hooks/guidedGate.ts), `ask_human` (a choice between options, in a panel, within the turn) and, when the
  * session can be in plan mode (`modeControl`), `present_plan`, the kit's own way out of plan
  * mode (ADR-023): the person runs the plan, keeps planning or cancels.
  */
 export declare function createHumanApprovalServer(runDir: string, texts?: HumanApprovalTexts, options?: {
-    modeControl?: ModeControl;
+    modeControl?: ModeControl; /** Each approval's answer: guided mode's batch (#74). */
+    onApproval?: (approved: boolean) => void;
 }): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/core/tools/humanApproval.js

@@ -16,7 +16,8 @@ const ok = (text) => ({ content: [{ type: "text", text }] });
 /**
  * The tools that ask the person, in every mode but autonomous: `request_human_approval`
  * (right before an action that publishes something visible to others and that's hard to
- * undo), `ask_human` (a choice between options, in a panel, within the turn) and, when the
+ * undo; approved, guided mode lets the calls that follow through until the person's next
+ * message, see hooks/guidedGate.ts), `ask_human` (a choice between options, in a panel, within the turn) and, when the
  * session can be in plan mode (`modeControl`), `present_plan`, the kit's own way out of plan
  * mode (ADR-023): the person runs the plan, keeps planning or cancels.
  */
@@ -29,6 +30,7 @@ export function createHumanApprovalServer(runDir, texts = DEFAULT_HUMAN_APPROVAL
             lines: [t().summaryLine(args.summary)],
         });
         const approved = APPROVED_ANSWERS.has(answer);
+        options.onApproval?.(approved);
         return {
             content: [{ type: "text", text: approved ? texts.approved : texts.rejected }],
         };

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { createPromptLoader } from "./core/promptTemplate.js";
 export { resolveClaudeAuth, type ClaudeAuthConfig } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
 export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withToolPhrases, type ToolDescriber, type ToolLabel, type ToolLabels, } from "./core/toolLabels.js";
-export type { Mode, BaseSessionConfig, AgentSpec, AgentIdentity, PlanModeSpec } from "./core/agentSpec.js";
+export type { Mode, BaseSessionConfig, AgentSpec, AgentIdentity, PlanModeSpec, ExtensionGateSpec } from "./core/agentSpec.js";
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode, type ModeControl, type ExtensionsStatus } from "./core/session.js";
 export { runQuery, type AgentEvent, type AgentRun, type SessionUsage, type ContextUsage } from "./core/runner.js";
 export type { McpAuthentication, SessionFacts } from "./core/sessionFacts.js";
@@ -17,7 +17,7 @@ export { knowledge, type KnowledgeOptions } from "./extensions/knowledge/index.j
 export { memory, type MemoryOptions } from "./extensions/memory/index.js";
 export { describeCapability, readExtensionManifest, type AboutExtension, type CapabilityText, type DescribedCapability, type Extension, type ExtensionCapability, type ExtensionContext, type ExtensionContribution, type ExtensionManifest, type FolderOption, type UnavailableCapability, } from "./core/extensions.js";
 export { checkRequirements, type ExtensionRequirement, type RequirementCheck } from "./core/extensionRequirements.js";
-export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type LocalServer, type RemoteServer, isRemoteServer, remoteHosts, remoteServerName, type InstalledExtension, type LockEntry, type ExtensionOptionState, } from "./core/externalExtensions.js";
+export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, setExtensionConfirm, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type LocalServer, type RemoteServer, isRemoteServer, remoteHosts, remoteServerName, type InstalledExtension, type LockEntry, type ExtensionOptionState, type ExtensionConfirm, type ToolConfirmation, } from "./core/externalExtensions.js";
 export type { ExtensionOption, OptionValue } from "./core/extensionOptions.js";
 export type { ExtensionAuth, ExtensionRestart, ExtensionSwitch, SignIn } from "./core/liveExtensions.js";
 export { packageCacheDir, type CachedPackage } from "./core/npxPackages.js";
@@ -41,6 +41,7 @@ export { createSubagentTypeGate } from "./core/hooks/subagentTypeGate.js";
 export { createSubagentForegroundGate } from "./core/hooks/subagentForegroundGate.js";
 export { createFileScopeGate, checkFileScope, type FileScope } from "./core/hooks/fileScopeGate.js";
 export { createPlanGate, checkPlanScope, type PlanScope } from "./core/hooks/planGate.js";
+export { createGuidedGate, type GuardedExtension, type GuidedDecision, type GuidedGate } from "./core/hooks/guidedGate.js";
 export { askForDecision, askForManualIntervention, askForChoice, askForText, type ChoiceAnswer } from "./core/hooks/humanInput.js";
 export { setInteractionPort, getInteractionPort, type InteractionPort, type ApprovalPrompt, type ChoiceSettings } from "./core/interaction.js";
 export { formFields, type FormAnswer, type FormField, type FormRequest } from "./core/elicitation.js";

package/dist/index.js

@@ -17,7 +17,7 @@ export { knowledge } from "./extensions/knowledge/index.js";
 export { memory } from "./extensions/memory/index.js";
 export { describeCapability, readExtensionManifest, } from "./core/extensions.js";
 export { checkRequirements } from "./core/extensionRequirements.js";
-export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, isRemoteServer, remoteHosts, remoteServerName, } from "./core/externalExtensions.js";
+export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, setExtensionConfirm, listInstalled, readExternalManifest, isRemoteServer, remoteHosts, remoteServerName, } from "./core/externalExtensions.js";
 export { packageCacheDir } from "./core/npxPackages.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, } from "./core/marketplaces.js";
 export { extensionCatalog, installExtension, restoreExtensions, updateExtension } from "./core/extensionCatalog.js";
@@ -40,6 +40,7 @@ export { createSubagentTypeGate } from "./core/hooks/subagentTypeGate.js";
 export { createSubagentForegroundGate } from "./core/hooks/subagentForegroundGate.js";
 export { createFileScopeGate, checkFileScope } from "./core/hooks/fileScopeGate.js";
 export { createPlanGate, checkPlanScope } from "./core/hooks/planGate.js";
+export { createGuidedGate } from "./core/hooks/guidedGate.js";
 export { askForDecision, askForManualIntervention, askForChoice, askForText } from "./core/hooks/humanInput.js";
 export { setInteractionPort, getInteractionPort } from "./core/interaction.js";
 export { formFields } from "./core/elicitation.js";

package/dist/tui/extensionCommand.d.ts

@@ -12,7 +12,7 @@ export { chatExtensionsCommand, describe } from "../chat/extensions.js";
  * - `extension add <folder> --link [--project]`: registered where it is, to develop it (not copied, its files not checked)
  * - `extension remove <name> [--project | --agent] [--yes | --keep-data]`: asks before deleting its data folder
  * - `extension enable|disable <name> [--project | --agent]`
- * - `extension config <name> [key=value… | key… | --unset key…] [--project | --agent]`: its options; `key` alone asks for it (without echo when it's a secret)
+ * - `extension config <name> [key=value… | key… | --unset key… | confirm=on|off|reset] [--project | --agent]`: its options; `key` alone asks for it (without echo when it's a secret); `confirm=` what guided mode asks about its tools (#74, #76)
  * - `extension update [name] [--yes]`: one installed from a marketplace (or all that have a newer version there) to the version it offers now, its data and options kept
  * - `extension restore [--trust]`: gets the code a workspace's lock lists and this computer lacks (#57); `--trust` trusts it too
  * - `extension trust [name…]`: lets a workspace's extensions run, as their code is now

package/dist/tui/extensionCommand.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, removeMarketplace, updateMarketplace, } from "../core/marketplaces.js";
 import { addExtension, extensionOptionStates, installTarget, folderSize, isGitSource, isRemoteServer, remoteHosts, listInstalled, removeExtension, setExtensionEnabled, setExtensionOptions, } from "../core/externalExtensions.js";
-import { describe, describeOptions } from "../chat/extensions.js";
+import { applyConfirm, describe, describeConfirm, describeOptions } from "../chat/extensions.js";
 import { extensionCatalog, knownMarketplaces as catalogMarketplaces, restoreExtensions, updateExtension } from "../core/extensionCatalog.js";
 import { trustWorkspace } from "../core/workspaceTrust.js";
 import { describeCapability, describeInLanguage } from "../core/extensions.js";
@@ -21,7 +21,7 @@ export { chatExtensionsCommand, describe } from "../chat/extensions.js";
  * - `extension add <folder> --link [--project]`: registered where it is, to develop it (not copied, its files not checked)
  * - `extension remove <name> [--project | --agent] [--yes | --keep-data]`: asks before deleting its data folder
  * - `extension enable|disable <name> [--project | --agent]`
- * - `extension config <name> [key=value… | key… | --unset key…] [--project | --agent]`: its options; `key` alone asks for it (without echo when it's a secret)
+ * - `extension config <name> [key=value… | key… | --unset key… | confirm=on|off|reset] [--project | --agent]`: its options; `key` alone asks for it (without echo when it's a secret); `confirm=` what guided mode asks about its tools (#74, #76)
  * - `extension update [name] [--yes]`: one installed from a marketplace (or all that have a newer version there) to the version it offers now, its data and options kept
  * - `extension restore [--trust]`: gets the code a workspace's lock lists and this computer lacks (#57); `--trust` trusts it too
  * - `extension trust [name…]`: lets a workspace's extensions run, as their code is now
@@ -200,16 +200,22 @@ export async function runExtensionCommand(argv, options) {
             case "config": {
                 const name = positional[0];
                 if (!name)
-                    return fail(`Usage: ${command} extension config <name> [key=value… | key… | --unset key…] [--project | --agent]`);
+                    return fail(`Usage: ${command} extension config <name> [key=value… | key… | --unset key… | confirm=on|off|reset] [--project | --agent]`);
                 const found = (await listInstalled(options.dirs)).filter((extension) => extension.name === name && !extension.shadowed && (!askedScope || extension.scope === askedScope));
                 if (!found.length)
                     return fail(`${name} isn't installed${askedScope ? ` in the ${askedScope} scope` : ""}. \`${command} extension list\` lists them.`);
                 const installed = found[0];
                 const declared = installed.manifest?.userConfig ?? {};
+                // Guided mode's answers about its tools (#74, #76): confirm=on|off|reset.
+                const confirm = await applyConfirm(installed, positional.slice(1));
+                if ("error" in confirm)
+                    return fail(`${confirm.error}.`);
+                if (confirm.changed)
+                    write(`${name}'s guided-mode answers saved in the ${installed.scope} scope.`);
                 const typed = {};
                 for (const key of values("unset"))
                     typed[key] = undefined;
-                for (const pair of positional.slice(1)) {
+                for (const pair of confirm.rest) {
                     const at = pair.indexOf("=");
                     if (at > 0)
                         typed[pair.slice(0, at)] = pair.slice(at + 1);
@@ -224,10 +230,11 @@ export async function runExtensionCommand(argv, options) {
                     await setExtensionOptions(installed, name, typed);
                     write(`${name}'s options saved in the ${installed.scope} scope. They apply when its server starts again: the next session, or in a chat \`/extensions disable ${name}\` and \`enable\`.`);
                 }
-                const lines = await describeOptions((await listInstalled(options.dirs)).find((extension) => extension.name === name && extension.scopeDir === installed.scopeDir));
+                const now = (await listInstalled(options.dirs)).find((extension) => extension.name === name && extension.scopeDir === installed.scopeDir);
+                const lines = await describeOptions(now);
                 if (!lines.length)
                     write(`${name} has no options.`);
-                for (const line of lines)
+                for (const line of [...lines, ...describeConfirm(now)])
                     write(line);
                 return true;
             }
@@ -297,6 +304,7 @@ export async function runExtensionCommand(argv, options) {
                     "  remove <name> [--project | --agent] [--yes | --keep-data]",
                     "  enable|disable <name> [--project | --agent]",
                     "  config <name> [key=value… | key… | --unset key…]   its options (key alone asks for it)",
+                    "  config <name> confirm=on|off|reset    whether guided mode asks before its tools, or forget the answers kept",
                     "  update [name]                          to the version its marketplace offers now (all that have one, without a name)",
                     "  restore [--trust]                      gets what this workspace's lock lists and this computer lacks",
                     "  trust [name…]                          lets this workspace's extensions run, as they are now",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",

package/schemas/agent-kit-metadata.schema.json

@@ -34,6 +34,11 @@
       "type": "array",
       "items": { "type": "string", "minLength": 1 }
     },
+    "confirmTools": {
+      "description": "Its tools that always ask the person in guided mode (short names), even inside a batch they approved, and are never offered \"always\": what creates, edits or publishes in their account. Without it, its servers' destructiveHint says which.",
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
     "labels": {
       "description": "How the chat shows each tool (short name), per language (en, es, fr, de): {field} takes the call's input.",
       "type": "object",