@falkenslab/agent-kit 0.29.0 → 0.30.0

package/dist/chat/extensions.d.ts

@@ -6,9 +6,10 @@ export declare function describe(extension: InstalledExtension): string;
 /**
  * What the active extensions let the agent do (#62), in the session's language: a heading per
  * extension with capabilities, a line per capability, and the tools a capability names that its
- * server doesn't offer, once the session has started and knows them.
+ * server doesn't offer, once the session has started and knows them. Not for one waiting for a
+ * sign-in (`waiting`): its tools aren't there until the person signs in, which `/extensions` says.
  */
-export declare function describeCapabilities(status: ExtensionsStatus): string[];
+export declare function describeCapabilities(status: ExtensionsStatus, waiting?: readonly string[]): string[];
 /** What the chat does for `/extensions install|update|remove|reload` (#56). */
 export type ExtensionAction = {
     type: "install";

package/dist/chat/extensions.js

@@ -15,9 +15,10 @@ export function describe(extension) {
 /**
  * What the active extensions let the agent do (#62), in the session's language: a heading per
  * extension with capabilities, a line per capability, and the tools a capability names that its
- * server doesn't offer, once the session has started and knows them.
+ * server doesn't offer, once the session has started and knows them. Not for one waiting for a
+ * sign-in (`waiting`): its tools aren't there until the person signs in, which `/extensions` says.
  */
-export function describeCapabilities(status) {
+export function describeCapabilities(status, waiting = []) {
     const offered = new Set(status.sessionTools?.() ?? []);
     return status.active.flatMap((name) => {
         const capabilities = status.about[name]?.capabilities ?? [];
@@ -27,7 +28,7 @@ export function describeCapabilities(status) {
         return [
             t().extensionCan(name),
             ...capabilities.map(({ label, description, tools }) => {
-                const missing = offered.size ? [...new Set(tools.filter((tool) => !offered.has(tool)).map((tool) => tool.replace(/^mcp__.+?__/, "")))] : [];
+                const missing = offered.size && !waiting.includes(name) ? [...new Set(tools.filter((tool) => !offered.has(tool)).map((tool) => tool.replace(/^mcp__.+?__/, "")))] : [];
                 return `  - ${label}${description ? `: ${description}` : ""}${missing.length ? ` ${t().capabilityToolsMissing(missing.join(", "))}` : ""}`;
             }),
             // What it can't do on this computer, with what to install (#63).
@@ -149,13 +150,21 @@ export async function chatExtensionsCommand(line, status, canReopen) {
     }
     if (!action) {
         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)));
+        if (status) {
+            const waiting = await needingSignIn(status);
+            lines.push(...describeCapabilities(status, waiting), ...waiting.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(", ")));
+        // The project's own .mcp.json servers left out (#83), by its folder's name: "<project>/.mcp.json".
+        const project = status?.projectServers;
+        if (project) {
+            const file = `${path.basename(path.dirname(project.file))}/.mcp.json`;
+            lines.push(t().projectServersDuplicated(file, project.duplicates.map(({ server, target }) => `${server} (${target})`).join(", ")));
+        }
         for (const { name: off, reason } of status?.inactive ?? [])
             lines.push(t().extensionOff(off, reason));
         if (status?.installed.length)

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

@@ -0,0 +1,24 @@
+import type { HookCallback, McpServerStatus } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * What the model is told about signing in to an installed extension (#82): an extension whose
+ * remote server waits for the person to sign in has no tools yet, nor the skill that would say
+ * how, so the model fell back on Claude Code's `/mcp`, `claude mcp` or claude.ai's connectors,
+ * none of which applies in an agent on the kit.
+ */
+export declare function signInInstruction(name: string): string;
+/** The system prompt's rule, for a session with installed extensions behind a sign-in. */
+export declare const SIGN_IN_RULE = "An installed extension whose remote server needs the person to sign in has no tools until they do: when one does, ask them to run `/extensions sign-in <extension>` (it opens their browser). Never suggest `/mcp`, `claude mcp` or claude.ai's connectors: they don't apply here.";
+/**
+ * A `UserPromptSubmit` hook (#82): with the person's message, tells the model which installed
+ * extensions now wait for a sign-in (at the start, after `/extensions sign-out`), once each until
+ * it's signed in again.
+ */
+export declare function createSignInReminder(options: {
+    /** Each installed extension's remote servers, by session name. */
+    extensions: () => readonly {
+        name: string;
+        remoteServers: readonly string[];
+    }[];
+    /** The running session's servers, as they are now. */
+    status: () => (() => Promise<McpServerStatus[]>) | undefined;
+}): HookCallback;

package/dist/core/hooks/signInReminder.js

@@ -0,0 +1,43 @@
+/**
+ * What the model is told about signing in to an installed extension (#82): an extension whose
+ * remote server waits for the person to sign in has no tools yet, nor the skill that would say
+ * how, so the model fell back on Claude Code's `/mcp`, `claude mcp` or claude.ai's connectors,
+ * none of which applies in an agent on the kit.
+ */
+export function signInInstruction(name) {
+    return `The ${name} extension needs the person to sign in before its tools are available: ask them to run \`/extensions sign-in ${name}\` (it opens their browser). Never suggest \`/mcp\`, \`claude mcp\` or claude.ai's connectors: they don't apply here.`;
+}
+/** The system prompt's rule, for a session with installed extensions behind a sign-in. */
+export const SIGN_IN_RULE = "An installed extension whose remote server needs the person to sign in has no tools until they do: when one does, ask them to run `/extensions sign-in <extension>` (it opens their browser). Never suggest `/mcp`, `claude mcp` or claude.ai's connectors: they don't apply here.";
+/**
+ * A `UserPromptSubmit` hook (#82): with the person's message, tells the model which installed
+ * extensions now wait for a sign-in (at the start, after `/extensions sign-out`), once each until
+ * it's signed in again.
+ */
+export function createSignInReminder(options) {
+    const reminded = new Set();
+    return async (input) => {
+        const read = options.status();
+        if (!read)
+            return {};
+        const statuses = await within(read(), []);
+        const waiting = new Set(statuses.filter((server) => server.status === "needs-auth").map((server) => server.name));
+        const notes = [];
+        for (const { name, remoteServers } of options.extensions()) {
+            if (!remoteServers.some((server) => waiting.has(server))) {
+                reminded.delete(name); // signed in (or off): a later sign-out reminds again
+                continue;
+            }
+            if (reminded.has(name))
+                continue;
+            reminded.add(name);
+            notes.push(signInInstruction(name));
+        }
+        if (!notes.length)
+            return {};
+        return { hookSpecificOutput: { hookEventName: input.hook_event_name, additionalContext: notes.join("\n") } };
+    };
+}
+// A call to the session made from a hook: never let it hold the person's message 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/messages/de.js

@@ -69,6 +69,7 @@ export const de = {
     confirmKept: (tool, answer) => `  ${tool}: ${answer === "always" ? "immer ja" : "nie"}`,
     confirmNoneKept: "  (keine gespeicherten Antworten; confirm=reset vergisst sie)",
     connectorsAllowed: (names) => `claude.ai-Connectoren: ${names}`,
+    projectServersDuplicated: (file, servers) => `${file} deklariert auch ${servers}: die der Erweiterungen werden verwendet`,
     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)`,
     extensionUpdated: (name, from, to) => `(${name} aktualisiert, ${from} → ${to}: in einem neuen Gespräch da, oder sofort mit /extensions reload)`,

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

@@ -104,6 +104,8 @@ export interface Messages {
     confirmNoneKept: string;
     /** In /extensions: the claude.ai connectors let in (#70). */
     connectorsAllowed(names: string): string;
+    /** In /extensions: the project's .mcp.json servers left out because an extension's duplicates them (#83). */
+    projectServersDuplicated(file: string, servers: string): string;
     /** In /extensions: connectors the agent asked for that the account hasn't. */
     connectorsMissing(names: string): string;
     extensionUpdated(name: string, from: string, to: string): string;

package/dist/core/messages/en.js

@@ -69,6 +69,7 @@ export const en = {
     confirmKept: (tool, answer) => `  ${tool}: ${answer === "always" ? "always yes" : "never"}`,
     confirmNoneKept: "  (no kept answers; confirm=reset forgets them)",
     connectorsAllowed: (names) => `claude.ai connectors: ${names}`,
+    projectServersDuplicated: (file, servers) => `${file} also declares ${servers}: the extensions' are used`,
     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)`,
     extensionsUpToDate: "(every extension from a marketplace is up to date)",

package/dist/core/messages/es.js

@@ -69,6 +69,7 @@ export const es = {
     confirmKept: (tool, answer) => `  ${tool}: ${answer === "always" ? "siempre sí" : "nunca"}`,
     confirmNoneKept: "  (ninguna respuesta guardada; confirm=reset las olvida)",
     connectorsAllowed: (names) => `Conectores de claude.ai: ${names}`,
+    projectServersDuplicated: (file, servers) => `${file} también declara ${servers}: se usan los de las extensiones`,
     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)`,
     extensionUpdated: (name, from, to) => `(${name} actualizada, ${from} → ${to}: está en una conversación nueva, o ya con /extensions reload)`,

package/dist/core/messages/fr.js

@@ -69,6 +69,7 @@ export const fr = {
     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}`,
+    projectServersDuplicated: (file, servers) => `${file} déclare aussi ${servers} : ceux des extensions sont utilisés`,
     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)`,
     extensionUpdated: (name, from, to) => `(${name} mise à jour, ${from} → ${to} : elle est là dans une nouvelle conversation, ou dès maintenant avec /extensions reload)`,

package/dist/core/projectServers.d.ts

@@ -0,0 +1,30 @@
+import { type PluginServer } from "./externalExtensions.js";
+/** A project server left out because an installed extension's is the same service (#83). */
+export interface ProjectServerDuplicate {
+    /** Its name in the project's `.mcp.json`. */
+    server: string;
+    /** What it is: the remote server's URL, or the npm package it runs. */
+    target: string;
+    /** The extension whose server is used instead. */
+    extension: string;
+}
+/** What a server is, to compare two: a remote one's URL, or the npm package an `npx` / `bunx` / `uvx` one runs (its version aside). */
+export declare function serverTarget(server: {
+    url?: string;
+    command?: string;
+    args?: string[];
+}): string | undefined;
+/**
+ * The servers of the project's `.mcp.json` an installed extension's server duplicates (#83): the
+ * same remote URL, or the same npm package, whose own sign-in notice and settings (another
+ * version, other courses) would sit beside the extension's and mislead the model. Every other
+ * project server stays: the agent can use them as Claude Code would. A name the kit passes itself
+ * is never left out: the denylist goes by name, and would take the kit's server too.
+ */
+export declare function projectServerDuplicates(projectDir: string, extensions: readonly {
+    name: string;
+    servers: Record<string, PluginServer>;
+}[], passed: ReadonlySet<string>): Promise<{
+    file: string;
+    duplicates: ProjectServerDuplicate[];
+} | undefined>;

package/dist/core/projectServers.js

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { isRemoteServer } from "./externalExtensions.js";
+/** What a server is, to compare two: a remote one's URL, or the npm package an `npx` / `bunx` / `uvx` one runs (its version aside). */
+export function serverTarget(server) {
+    if (typeof server.url === "string" && server.url)
+        return server.url.trim().toLowerCase().replace(/\/+$/, "");
+    if (typeof server.command !== "string")
+        return undefined;
+    const runner = path.basename(server.command).toLowerCase().replace(/\.(cmd|exe)$/, "");
+    if (!["npx", "bunx", "uvx", "pnpx"].includes(runner))
+        return undefined;
+    const spec = (server.args ?? []).find((arg) => typeof arg === "string" && !arg.startsWith("-"));
+    if (!spec)
+        return undefined;
+    // @scope/name@1.2.3 → @scope/name; name@1 → name.
+    const at = spec.indexOf("@", spec.startsWith("@") ? 1 : 0);
+    return (at > 0 ? spec.slice(0, at) : spec).toLowerCase();
+}
+/**
+ * The servers of the project's `.mcp.json` an installed extension's server duplicates (#83): the
+ * same remote URL, or the same npm package, whose own sign-in notice and settings (another
+ * version, other courses) would sit beside the extension's and mislead the model. Every other
+ * project server stays: the agent can use them as Claude Code would. A name the kit passes itself
+ * is never left out: the denylist goes by name, and would take the kit's server too.
+ */
+export async function projectServerDuplicates(projectDir, extensions, passed) {
+    const file = path.join(projectDir, ".mcp.json");
+    let servers;
+    try {
+        const raw = JSON.parse(await readFile(file, "utf8"));
+        servers = raw.mcpServers && typeof raw.mcpServers === "object" ? raw.mcpServers : {};
+    }
+    catch {
+        return undefined;
+    }
+    const theirs = extensions.flatMap(({ name, servers: own }) => Object.values(own).flatMap((server) => {
+        const target = serverTarget(isRemoteServer(server) ? { url: server.url } : server);
+        return target ? [{ extension: name, target }] : [];
+    }));
+    const duplicates = [];
+    for (const [name, server] of Object.entries(servers)) {
+        if (passed.has(name) || !server || typeof server !== "object")
+            continue;
+        const target = serverTarget(server);
+        const same = target ? theirs.find((candidate) => candidate.target === target) : undefined;
+        if (same)
+            duplicates.push({ server: name, target: server.url ?? target, extension: same.extension });
+    }
+    return duplicates.length ? { file, duplicates } : undefined;
+}

package/dist/core/session.d.ts

@@ -7,6 +7,7 @@ import type { ToolLabels } from "./toolLabels.js";
 import type { AgentSpec, BaseSessionConfig } from "./agentSpec.js";
 import { type Language } from "./language.js";
 import { type RunFolder } from "./runs.js";
+import { type ProjectServersLeftOut } from "./sessionFacts.js";
 import { type ExtensionAuth, type ExtensionRestart, type ExtensionSwitch } from "./liveExtensions.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
@@ -82,6 +83,8 @@ export interface ExtensionsStatus {
         allowed: string[];
         missing: string[];
     };
+    /** The project's `.mcp.json` servers left out (#83). */
+    projectServers?: ProjectServersLeftOut;
 }
 /**
  * The CLI's folder for a project, where it keeps each session's transcript and large tool

package/dist/core/session.js

@@ -29,6 +29,8 @@ import { createExtensionAuth, createExtensionRestart, createExtensionSwitch, mou
 import { secretsDir } from "./extensionOptions.js";
 import { createElicitationHandler } from "./elicitation.js";
 import { createReadOnlyHints, createToolHints } from "./readOnlyHints.js";
+import { projectServerDuplicates } from "./projectServers.js";
+import { createSignInReminder, SIGN_IN_RULE } from "./hooks/signInReminder.js";
 import { agentKitVersion } from "./version.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
@@ -229,10 +231,14 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             record: (decision) => transcriptLogger.note("guided_decision", { ...decision }),
         })
         : undefined;
+    // The installed extensions with remote servers, which may need the person to sign in (#82).
+    const signInExtensions = resolved.active.flatMap(({ extension }, index) => (added[index]?.remoteServers?.length ? [{ name: extension.name, remoteServers: added[index].remoteServers }] : []));
     const promptSections = [
         spec.buildSystemPrompt(config),
         // What's on and what isn't, then the extensions' own sections.
         ...(resolved.active.length || resolved.inactive.length ? [extensionsPromptSection(resolved)] : []),
+        // How a sign-in is done here, never Claude Code's way (#82).
+        ...(signInExtensions.length ? [SIGN_IN_RULE] : []),
         // The extensions' own sections, in their order (the sources' before the knowledge base's).
         ...fromExtensions((contribution) => (contribution.promptSection ? [contribution.promptSection] : [])),
     ];
@@ -400,10 +406,29 @@ 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] }] } : {}),
+            // The person's message: it ends a batch they approved (#74), and carries the sign-in reminders (#82).
+            ...(guidedGate || signInExtensions.length
+                ? {
+                    UserPromptSubmit: [
+                        ...(guidedGate ? [{ hooks: [guidedGate.userPromptSubmit] }] : []),
+                        // With the person's message, which extensions now wait for a sign-in (#82).
+                        ...(signInExtensions.length ? [{ hooks: [createSignInReminder({ extensions: () => signInExtensions, status: () => late.view?.controls().mcpServerStatus })] }] : []),
+                    ],
+                }
+                : {}),
         },
     };
+    // A project's own .mcp.json beside the extensions (#83): only a server an extension's duplicates
+    // is left out, by name, as the connectors not chosen are (#70), never switched off (the CLI saves
+    // that, #75). Every other project server stays. Names the kit passes stay too.
+    const installedNow = await listInstalled(extensionDirs);
+    const projectServersLeftOut = (spec.settingSources ?? ["project"]).includes("project")
+        ? await projectServerDuplicates(config.projectDir, installedNow.filter((installed) => !installed.shadowed && installedDirs.has(installed.name) && installed.manifest).map((installed) => ({ name: installed.name, servers: installed.manifest.servers })), new Set(Object.keys(sdkOptions.mcpServers ?? {})))
+        : undefined;
+    if (projectServersLeftOut) {
+        const settings = sdkOptions.settings;
+        settings.deniedMcpServers = [...(settings.deniedMcpServers ?? []), ...projectServersLeftOut.duplicates.map(({ server }) => ({ serverName: server }))];
+    }
     // Where each remote server's calls go (#70), for the remote gate: an http/sse server's host
     // (an installed extension's, the agent's own), or the claude.ai connector itself.
     const remoteDestinations = [
@@ -434,13 +459,14 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         ...(config.officialMarketplace ? { official: config.officialMarketplace } : {}),
         ...(config.catalogTopics?.length ? { catalogTopics: config.catalogTopics } : {}),
         untrusted: external.untrusted.map((installed) => ({ name: installed.name, ...(installed.manifest?.version ? { version: installed.manifest.version } : {}), source: installed.lock.marketplace ?? installed.lock.source })),
-        installed: await listInstalled(extensionDirs),
+        installed: installedNow,
         active: resolved.active.map(({ extension }) => extension.name),
         about: Object.fromEntries(resolved.active.map(({ extension, manifest, unavailable }, index) => [extension.name, aboutExtension(manifest, Object.keys(added[index]?.mcpServers ?? {}), language, unavailable)])),
         sessionTools: () => late.view?.controls().tools ?? [],
         serverStatus: async () => (await late.view?.controls().mcpServerStatus?.().catch(() => [])) ?? [],
         inactive: resolved.inactive,
         ...(connectors ? { connectors: { allowed: connectors.allowed, missing: connectors.missing } } : {}),
+        ...(projectServersLeftOut ? { projectServers: projectServersLeftOut } : {}),
     };
     // What the session is, for the extensions that ask (sessionFacts.ts, #43).
     const viewBase = {
@@ -460,6 +486,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             // Its own list: /extensions' status has another, and the live switch changes both.
             inactive: [...resolved.inactive],
             ...(connectors ? { connectors: { allowed: connectors.allowed, missing: connectors.missing } } : {}),
+            ...(projectServersLeftOut ? { projectServers: projectServersLeftOut } : {}),
         },
         subagents: Object.entries(allAgents).map(([name, agent]) => ({ name, description: agent.description })),
         skills: sdkOptions.skills === "all" ? await pluginSkills(pluginRoots) : [...(sdkOptions.skills ?? [])],

package/dist/core/sessionFacts.d.ts

@@ -42,6 +42,10 @@ export interface SessionFacts {
             allowed: string[];
             missing: string[];
         };
+        /** The project's `.mcp.json` servers left out because an extension's duplicates them (#83). */
+        projectServers?: ProjectServersLeftOut;
+        /** The running extensions waiting for the person to sign in to a remote server (#82): `/extensions sign-in <name>`. */
+        needSignIn?: string[];
     };
     /** The subagents it can delegate to. */
     subagents: {
@@ -99,8 +103,20 @@ export type StaticSessionFacts = Omit<SessionFacts, "mode" | "switchableModes" |
         })[];
         inactive: SessionFacts["extensions"]["inactive"];
         connectors?: SessionFacts["extensions"]["connectors"];
+        projectServers?: ProjectServersLeftOut;
     };
 };
+/** The project's `.mcp.json` servers a session leaves out because an extension's duplicates them (#83). */
+export interface ProjectServersLeftOut {
+    /** The project's `.mcp.json`. */
+    file: string;
+    /** Those an installed extension's server duplicates: its name there, what it is (a URL, an npm package), and the extension used instead. */
+    duplicates: {
+        server: string;
+        target: string;
+        extension: string;
+    }[];
+}
 export interface SessionView {
     facts(): Promise<SessionFacts>;
     attach(live: SessionLive): void;

package/dist/core/sessionFacts.js

@@ -11,10 +11,14 @@ export function createSessionView(base, modeControl) {
         controls: () => live,
         async facts() {
             const tools = live.tools ?? [];
-            const [commands, context] = await Promise.all([
+            const [commands, context, statuses] = await Promise.all([
                 live.supportedCommands ? within(live.supportedCommands(), []) : Promise.resolve([]),
                 live.contextUsage ? within(live.contextUsage(), null) : Promise.resolve(null),
+                live.mcpServerStatus ? within(live.mcpServerStatus(), []) : Promise.resolve([]),
             ]);
+            // Those whose remote server waits for the person to sign in (#82).
+            const waiting = new Set(statuses.filter((server) => server.status === "needs-auth").map((server) => server.name));
+            const needSignIn = base.extensions.active.filter(({ servers }) => servers.some((server) => waiting.has(server))).map(({ name }) => name);
             return {
                 ...base,
                 mode: modeControl.mode,
@@ -27,6 +31,8 @@ export function createSessionView(base, modeControl) {
                     })),
                     inactive: base.extensions.inactive,
                     ...(base.extensions.connectors ? { connectors: base.extensions.connectors } : {}),
+                    ...(base.extensions.projectServers ? { projectServers: base.extensions.projectServers } : {}),
+                    ...(needSignIn.length ? { needSignIn } : {}),
                 },
                 tools,
                 skills: live.skills ?? base.skills,

package/dist/extensions/awareness/tools.js

@@ -33,6 +33,17 @@ export function describeSession(facts) {
         const missing = connectors.missing.length ? ` Asked for but not in the person's claude.ai account: ${connectors.missing.join(", ")} (they connect it on claude.ai, then the session opens again).` : "";
         sections.push(`## claude.ai connectors\n\n${connectors.allowed.length ? `${connectors.allowed.join(", ")}: their tools are the person's claude.ai integrations; what you send them leaves the computer.` : "None of the ones asked for."}${missing}`);
     }
+    // Extensions waiting for the person to sign in (#82): their tools aren't there until they do.
+    const waiting = facts.extensions.needSignIn ?? [];
+    if (waiting.length) {
+        sections.push(`## Waiting for a sign-in\n\n${waiting.map((name) => `- **${name}**: its tools aren't available until the person signs in: ask them to run \`/extensions sign-in ${name}\` (it opens their browser).`).join("\n")}\nNever suggest \`/mcp\`, \`claude mcp\` or claude.ai's connectors: they don't apply here.`);
+    }
+    // The project's own .mcp.json servers left out (#83): not this session's, whatever a notice about them says.
+    const project = facts.extensions.projectServers;
+    if (project) {
+        const duplicates = project.duplicates.map(({ server, target, extension }) => `- **${server}** (${target}): left out, the ${extension} extension's server is used instead.`);
+        sections.push(`## Servers of the project's .mcp.json left out\n\n${duplicates.join("\n")}\nA notice about one of them (such as one needing authentication) isn't about your extensions.`);
+    }
     if (facts.subagents.length)
         sections.push(`## Subagents you can delegate to\n\n${facts.subagents.map(({ name, description }) => `- **${name}**: ${description}`).join("\n")}`);
     const own = facts.tools.filter((tool) => !tool.startsWith("mcp__"));

package/dist/tui/extensionCommand.js

@@ -9,6 +9,30 @@ import { trustWorkspace } from "../core/workspaceTrust.js";
 import { describeCapability, describeInLanguage } from "../core/extensions.js";
 import { getLanguage } from "../core/messages/index.js";
 export { chatExtensionsCommand, describe } from "../chat/extensions.js";
+/**
+ * Each action's usage and the flags it takes (#81): `--help` prints the usage, and a flag it
+ * doesn't take fails instead of being ignored, so a command that changes extensions never runs
+ * on a guess (`update --help` updated them all).
+ */
+const ACTIONS = {
+    list: { usage: ["list"], flags: [] },
+    info: { usage: ["info <name>"], flags: [] },
+    add: {
+        usage: ["add <folder | git URL[#ref] | plugin[@marketplace]> [--project | --agent] [--path <subfolder>] [--set key=value…] [--yes]", "add <folder> --link [--project]"],
+        flags: ["project", "agent", "path", "set", "yes", "link"],
+    },
+    remove: { usage: ["remove <name> [--project | --agent] [--yes | --keep-data]"], flags: ["project", "agent", "yes", "keep-data"] },
+    enable: { usage: ["enable <name> [--project | --agent]"], flags: ["project", "agent"] },
+    disable: { usage: ["disable <name> [--project | --agent]"], flags: ["project", "agent"] },
+    config: { usage: ["config <name> [key=value… | key… | --unset key… | confirm=on|off|reset] [--project | --agent]"], flags: ["project", "agent", "unset"] },
+    update: { usage: ["update [name] [--yes]"], flags: ["yes"] },
+    restore: { usage: ["restore [--trust]"], flags: ["trust"] },
+    trust: { usage: ["trust [name…]"], flags: [] },
+    search: { usage: ["search [words]"], flags: [] },
+    marketplace: { usage: ["marketplace add <folder | git URL[#ref] | owner/repo> [--yes]", "marketplace list | update [name] | remove <name>"], flags: ["yes"] },
+};
+/** Flags followed by a value of their own, which isn't a flag. */
+const VALUE_FLAGS = ["--path", "--set", "--unset"];
 /**
  * The `extension` command an agent exposes in its own binary (#37), e.g. `captain extension add
  * ./jokebook --project`: installs, removes, enables, disables and lists the extensions in its two
@@ -101,6 +125,19 @@ export async function runExtensionCommand(argv, options) {
     const confirmed = async (question, accepts) => flag("yes") || accepts((await ask(question)).trim());
     // The agent's own marketplace, known without asking; a folder is copied afresh each time (it's the agent's own code).
     const knownMarketplaces = () => catalogMarketplaces(options.dirs, options.official);
+    // Its usage with --help, and a flag it doesn't take refused, before anything changes (#81).
+    const known = ACTIONS[action ?? ""];
+    if (known) {
+        const usage = known.usage.map((line, index) => `${index === 0 ? "Usage: " : "       "}${command} extension ${line}`).join("\n");
+        const flags = rest.filter((arg, index) => (arg.startsWith("--") || arg === "-h") && !VALUE_FLAGS.includes(rest[index - 1]));
+        if (flags.some((arg) => arg === "--help" || arg === "-h")) {
+            write(usage);
+            return true;
+        }
+        const unknown = flags.filter((arg) => !known.flags.includes(arg.slice(2)));
+        if (unknown.length)
+            return fail(`${command} extension ${action} doesn't take ${unknown.join(", ")}.\n${usage}`);
+    }
     try {
         switch (action) {
             case "list": {

package/package.json

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

package/schemas/marketplace-catalog.schema.json

@@ -1,94 +1,133 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://falkenslab.github.io/agent-kit/schemas/marketplace-catalog.schema.json",
-  "title": "A marketplace's catalog.json",
-  "description": "A Claude Code marketplace's extensions as one file, for a page or a client to show without cloning the repository: written by @falkenslab/agent-kit-catalog from .claude-plugin/marketplace.json and each extension's plugin.json.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["marketplace", "description", "repository", "add", "extensions"],
-  "properties": {
-    "marketplace": { "description": "The marketplace's name, as <extension>@<marketplace> names an extension.", "type": "string", "minLength": 1 },
-    "description": { "type": "string" },
-    "repository": { "description": "The GitHub repository's page.", "type": "string", "pattern": "^https://github\\.com/[\\w.-]+/[\\w.-]+$" },
-    "add": {
-      "description": "How to add the marketplace.",
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["claudeCode", "agentKit"],
-      "properties": {
-        "claudeCode": { "type": "string" },
-        "agentKit": { "description": "After the agent's own command (<agent> …).", "type": "string" }
-      }
-    },
-    "extensions": {
-      "description": "Sorted by name.",
-      "type": "array",
-      "items": { "$ref": "#/$defs/extension" }
-    }
-  },
-  "$defs": {
-    "url": { "type": "string", "pattern": "^https://" },
-    "extension": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["name", "version", "description", "category", "topics", "author", "license", "homepage", "readme", "install"],
-      "properties": {
-        "name": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
-        "version": { "description": "Its plugin.json's, the same as its marketplace entry's.", "type": "string", "minLength": 1 },
-        "description": { "description": "In English: its marketplace entry's, else its plugin.json's.", "type": "string" },
-        "descriptions": {
-          "description": "Its description per language, English among them; only when it has one in another language.",
-          "type": "object",
-          "propertyNames": { "enum": ["en", "es", "fr", "de"] },
-          "required": ["en"],
-          "additionalProperties": { "type": "string" }
-        },
-        "category": { "type": ["string", "null"] },
-        "topics": {
-          "description": "Its plugin.json's keywords and its entry's tags, keywords and category, lowercased, without repeats.",
-          "type": "array",
-          "uniqueItems": true,
-          "items": { "type": "string", "pattern": "^[^A-Z]+$" }
-        },
-        "author": { "type": ["string", "null"] },
-        "license": { "type": ["string", "null"] },
-        "homepage": { "$ref": "#/$defs/url" },
-        "readme": { "$ref": "#/$defs/url" },
-        "readmes": {
-          "description": "Its README per language (README.md, README.es.md…), as URLs; only when it has one in another language.",
-          "type": "object",
-          "propertyNames": { "enum": ["en", "es", "fr", "de"] },
-          "required": ["en"],
-          "additionalProperties": { "$ref": "#/$defs/url" }
-        },
-        "install": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["claudeCode", "agentKit"],
-          "properties": {
-            "claudeCode": { "type": "string" },
-            "agentKit": { "description": "After the agent's own command (<agent> …).", "type": "string" }
-          }
-        },
-        "capabilities": {
-          "description": "What it lets the agent do: its metadata[\"agent-kit\"].capabilities as it declares them, texts in every language it gives.",
-          "type": "array",
-          "items": { "$ref": "https://falkenslab.github.io/agent-kit/schemas/agent-kit-metadata.schema.json#/$defs/capability" }
-        },
-        "requirements": {
-          "description": "The programs it needs on the computer: its metadata[\"agent-kit\"].requirements as it declares them.",
-          "type": "array",
-          "items": { "$ref": "https://falkenslab.github.io/agent-kit/schemas/agent-kit-metadata.schema.json#/$defs/requirement" }
-        },
-        "remote": {
-          "description": "The hosts its remote MCP servers talk to (type http or sse in its .mcp.json): what an agent sends there leaves the computer. Only when it has some.",
-          "type": "array",
-          "uniqueItems": true,
-          "items": { "type": "string", "minLength": 1 }
-        },
-        "logo": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" },
-        "banner": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" }
-      }
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://falkenslab.github.io/agent-kit/schemas/marketplace-catalog.schema.json",
+  "title": "A marketplace's catalog.json",
+  "description": "A Claude Code marketplace's extensions as one file, for a page or a client to show without cloning the repository: written by @falkenslab/agent-kit-catalog from .claude-plugin/marketplace.json and each extension's plugin.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["marketplace", "description", "repository", "add", "extensions"],
+  "properties": {
+    "marketplace": { "description": "The marketplace's name, as <extension>@<marketplace> names an extension.", "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "repository": { "description": "The GitHub repository's page.", "type": "string", "pattern": "^https://github\\.com/[\\w.-]+/[\\w.-]+$" },
+    "add": {
+      "description": "How to add the marketplace.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["claudeCode", "agentKit"],
+      "properties": {
+        "claudeCode": { "type": "string" },
+        "agentKit": { "description": "After the agent's own command (<agent> …).", "type": "string" }
+      }
+    },
+    "extensions": {
+      "description": "Sorted by name.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/extension" }
+    }
+  },
+  "$defs": {
+    "url": { "type": "string", "pattern": "^https://" },
+    "named": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" } } } },
+    "extension": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "description", "category", "topics", "author", "license", "homepage", "readme", "install"],
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+        "version": { "description": "Its plugin.json's, the same as its marketplace entry's.", "type": "string", "minLength": 1 },
+        "description": { "description": "In English: its marketplace entry's, else its plugin.json's.", "type": "string" },
+        "descriptions": {
+          "description": "Its description per language, English among them; only when it has one in another language.",
+          "type": "object",
+          "propertyNames": { "enum": ["en", "es", "fr", "de"] },
+          "required": ["en"],
+          "additionalProperties": { "type": "string" }
+        },
+        "category": { "type": ["string", "null"] },
+        "topics": {
+          "description": "Its plugin.json's keywords and its entry's tags, keywords and category, lowercased, without repeats.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[^A-Z]+$" }
+        },
+        "author": { "type": ["string", "null"] },
+        "license": { "type": ["string", "null"] },
+        "homepage": { "$ref": "#/$defs/url" },
+        "readme": { "$ref": "#/$defs/url" },
+        "readmes": {
+          "description": "Its README per language (README.md, README.es.md…), as URLs; only when it has one in another language.",
+          "type": "object",
+          "propertyNames": { "enum": ["en", "es", "fr", "de"] },
+          "required": ["en"],
+          "additionalProperties": { "$ref": "#/$defs/url" }
+        },
+        "install": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["claudeCode", "agentKit"],
+          "properties": {
+            "claudeCode": { "type": "string" },
+            "agentKit": { "description": "After the agent's own command (<agent> …).", "type": "string" }
+          }
+        },
+        "capabilities": {
+          "description": "What it lets the agent do: its metadata[\"agent-kit\"].capabilities as it declares them, texts in every language it gives.",
+          "type": "array",
+          "items": { "$ref": "https://falkenslab.github.io/agent-kit/schemas/agent-kit-metadata.schema.json#/$defs/capability" }
+        },
+        "requirements": {
+          "description": "The programs it needs on the computer: its metadata[\"agent-kit\"].requirements as it declares them.",
+          "type": "array",
+          "items": { "$ref": "https://falkenslab.github.io/agent-kit/schemas/agent-kit-metadata.schema.json#/$defs/requirement" }
+        },
+        "remote": {
+          "description": "The hosts its remote MCP servers talk to (type http or sse in its .mcp.json): what an agent sends there leaves the computer. Only when it has some.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "servers": {
+          "description": "Its MCP servers (plugin.json's mcpServers, else .mcp.json): a package run with npx, bunx or uvx (its package, version and npm page), a program it brings (bundled: its command as written), a remote server (its transport and host), or another command (its name only). Never an argument's secret nor an env value.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "kind"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "kind": { "enum": ["package", "bundled", "remote", "command"] },
+              "package": { "type": "string" },
+              "version": { "type": "string" },
+              "url": { "$ref": "#/$defs/url" },
+              "command": { "type": "string" },
+              "transport": { "enum": ["http", "sse"] },
+              "host": { "type": "string" }
+            }
+          }
+        },
+        "skills": { "description": "Its skills: each one's folder name and its SKILL.md's description, sorted by name.", "$ref": "#/$defs/named" },
+        "commands": { "description": "Its commands: each one's file name and its description, sorted by name.", "$ref": "#/$defs/named" },
+        "agents": { "description": "Its subagents: each one's file name and its description, sorted by name.", "$ref": "#/$defs/named" },
+        "tools": {
+          "description": "The tools its metadata[\"agent-kit\"] knows (labels, capabilities, readOnlyTools, confirmTools, serverConfirmTools), by short name: a static read, a running server may list more.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "labels": { "description": "Its label per language, {field} as written.", "type": "object", "propertyNames": { "enum": ["en", "es", "fr", "de"] }, "additionalProperties": { "type": "string" } },
+              "readOnly": { "description": "It only reads.", "const": true },
+              "confirm": { "description": "always: the person says yes before every call; server: its server asks the person itself.", "enum": ["always", "server"] }
+            }
+          }
+        },
+        "kit": { "description": "The agent-kit versions it works with, as its metadata[\"agent-kit\"].kit says.", "type": "string" },
+        "logo": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" },
+        "banner": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" }
+      }
+    }
+  }
+}