@falkenslab/agent-kit 0.28.0 → 0.30.0

package/dist/chat/chatController.d.ts

@@ -7,7 +7,7 @@ import { type AgentEvent, type AgentRun, type SessionUsage } from "../core/runne
 import { type RunFolder } from "../core/runs.js";
 import { type ExtensionsStatus, type ModeControl } from "../core/session.js";
 import { type Todo } from "../core/todos.js";
-import { type ToolLabels } from "../core/toolLabels.js";
+import { type ToolLabels, type ToolResult } from "../core/toolLabels.js";
 import type { ToolPhrase } from "../core/messages/index.js";
 import type { SignIn } from "../core/liveExtensions.js";
 import { type ExtensionOptionState, type ExtensionScope } from "../core/externalExtensions.js";
@@ -42,6 +42,8 @@ export interface ChatSettings {
     /** Tool call labels and folded-group phrases on top of the kit's and the extensions'. */
     formatAction?: (toolName: string, input: unknown) => string;
     toolPhrase?: (toolName: string) => ToolPhrase | undefined;
+    /** The line under a tool call for its result, before the labels' own (`ToolLabel.result`, #79): a string replaces it, `null` hides it, `undefined` leaves it to them. */
+    formatResult?: (toolName: string, result: ToolResult) => string | null | undefined;
     /** Runs the agent: the SDK's (`runQuery()`) by default; another for tests, or a host of its own. */
     runQuery?: (prompt: AsyncIterable<SDKUserMessage>, options: Options) => AgentRun;
     /** The SDK's prompt suggestions (on by default). */
@@ -223,9 +225,10 @@ export declare function createChatController(options: Options | SessionOpener, s
     subscribe(listener: (state: ChatState) => void): () => void;
     /** Calls `listener` with every event, in order; returns how to stop. */
     onEvent(listener: (event: ChatEvent) => void): () => void;
-    /** Tool call labels and phrases with the extensions' (for a view that renders events itself). */
+    /** Tool call labels, phrases and result lines with the extensions' (for a view that renders events itself). */
     formatAction: (toolName: string, toolInput: unknown) => string;
     toolPhrase: (toolName: string) => ToolPhrase | undefined;
+    formatResult: (toolName: string, result: ToolResult) => string | null | undefined;
     /** The folder the session works in. */
     cwd: () => string;
     /** Draws the run's earlier conversation, then sends the initial prompt (for a new run). */

package/dist/chat/chatController.js

@@ -7,7 +7,7 @@ import { runQuery } from "../core/runner.js";
 import { createRunFolder, listRuns, readConversation, readRunSession } from "../core/runs.js";
 import { createInputQueue, togglePlanMode } from "../core/session.js";
 import { hasOpenTodos, parseTodos, TODO_TOOL } from "../core/todos.js";
-import { withToolLabels, withToolPhrases } from "../core/toolLabels.js";
+import { withToolLabels, withToolPhrases, withToolResults } from "../core/toolLabels.js";
 import { createConsoleRenderer } from "../tui/consoleRenderer.js";
 import { chatExtensionsCommand } from "./extensions.js";
 import { trustWorkspace } from "../core/workspaceTrust.js";
@@ -39,6 +39,7 @@ export async function createChatController(options, settings = {}) {
     const modeControl = () => current.modeControl ?? settings.modeControl;
     const formatAction = withToolLabels(() => current.toolLabels ?? settings.toolLabels, settings.formatAction);
     const toolPhrase = withToolPhrases(() => current.toolLabels ?? settings.toolLabels, settings.toolPhrase);
+    const formatResult = withToolResults(() => current.toolLabels ?? settings.toolLabels, settings.formatResult);
     // State and listeners.
     const stateListeners = new Set();
     const eventListeners = new Set();
@@ -425,9 +426,10 @@ export async function createChatController(options, settings = {}) {
             eventListeners.add(listener);
             return () => eventListeners.delete(listener);
         },
-        /** Tool call labels and phrases with the extensions' (for a view that renders events itself). */
+        /** Tool call labels, phrases and result lines with the extensions' (for a view that renders events itself). */
         formatAction,
         toolPhrase,
+        formatResult,
         /** The folder the session works in. */
         cwd: () => current.options.cwd ?? process.cwd(),
         /** Draws the run's earlier conversation, then sends the initial prompt (for a new run). */

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/agentSpec.d.ts

@@ -219,8 +219,8 @@ 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`.
+     * Tools that always ask, on every call and even inside a batch the person approved (never
+     * offered "this session" or "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. */

package/dist/core/extensions.d.ts

@@ -71,6 +71,8 @@ export interface ExtensionContribution {
     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 tools whose server asks the person itself (MCP elicitation), by full name: guided mode doesn't ask too (#77). */
+    serverConfirmTools?: 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

@@ -58,6 +58,8 @@ export declare function remoteHosts(manifest: Pick<ExternalManifest, "servers">)
 export interface ExternalToolLabel {
     label: string;
     phrase?: ToolPhrase;
+    /** The line under the call when it succeeded, instead of its result's first line, written for the model (#79). */
+    result?: string;
 }
 /** Who made an extension, as Claude Code's `plugin.json` has it. */
 export interface ExtensionAuthor {
@@ -102,11 +104,16 @@ export interface ExternalManifest {
      */
     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.
+     * Its tools that always ask the person in guided mode (short names), on every call and even
+     * inside a batch they approved, never offering "this session" or "always" (#76, #78): what
+     * creates, edits or publishes in their account. Without the key, its servers' `destructiveHint` says which.
      */
     confirmTools?: string[];
+    /**
+     * Its tools whose server asks the person itself before acting, through MCP elicitation (short
+     * names, #77): guided mode doesn't ask too while the person can be asked, so it's one question.
+     */
+    serverConfirmTools?: 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`). */

package/dist/core/externalExtensions.js

@@ -141,6 +141,7 @@ export async function readExternalManifest(dir) {
         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") } : {}),
+        ...(Array.isArray(kit.serverConfirmTools) ? { serverConfirmTools: kit.serverConfirmTools.filter((tool) => typeof tool === "string") } : {}),
         labels: kit.labels ?? {},
         ...(kit.help ? { help: kit.help } : {}),
         userConfig: parseUserConfig(raw.userConfig),
@@ -367,7 +368,12 @@ function manifestToolLabels(manifest, sessionServers) {
         const texts = byLanguage[language] ?? byLanguage.en;
         if (!texts)
             return [];
-        const label = { label: (input) => fill(texts.label, input), ...(texts.phrase ? { phrase: texts.phrase } : {}) };
+        const label = {
+            label: (input) => fill(texts.label, input),
+            ...(texts.phrase ? { phrase: texts.phrase } : {}),
+            // In the person's language when it succeeded; a failure keeps its own line (#79).
+            ...(texts.result ? { result: (result) => (result.isError ? undefined : texts.result) } : {}),
+        };
         return sessionServers.map((server) => [`mcp__${server}__${tool}`, label]);
     }));
 }
@@ -429,6 +435,8 @@ function externalExtension(installed, manifest, cache, unavailable = []) {
                 ...(manifest.confirmTools
                     ? { confirmTools: Object.keys(servers).flatMap((server) => manifest.confirmTools.map((tool) => `mcp__${server}__${tool}`)) }
                     : { confirmHintServers: Object.keys(servers) }),
+                // And those whose server asks the person itself (#77).
+                ...(manifest.serverConfirmTools ? { serverConfirmTools: Object.keys(servers).flatMap((server) => manifest.serverConfirmTools.map((tool) => `mcp__${server}__${tool}`)) } : {}),
                 toolLabels: manifestToolLabels(manifest, Object.keys(servers)),
                 ...(remote.length ? { remoteServers: remote } : {}),
                 ...(manifest.help ? { helpLines: [manifest.help] } : {}),

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

@@ -10,12 +10,14 @@ export interface GuardedExtension {
     servers: readonly string[];
     /** Its tools that always ask (full names): its manifest's `confirmTools` and the agent's own list. */
     confirmTools: readonly string[];
+    /** Its tools whose server asks the person itself (full names, the manifest's `serverConfirmTools`, #77). */
+    serverConfirmTools?: 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";
+    answer: "yes" | "session" | "always" | "no" | "never" | "kept-never" | "autonomous-deny" | "server-asks";
 }
 /** The guided gate: its `PreToolUse` hook, and what ends or starts an approved batch. */
 export interface GuidedGate {
@@ -37,8 +39,10 @@ export interface GuidedGate {
  * 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.
+ * `destructiveHint`, asked on every call, so they're offered only yes, no and never (#78). An extension whose lock says `off`
+ * runs without asking. A tool whose server asks the person itself (`serverConfirmTools`, #77)
+ * isn't asked about too in guided mode, where that question reaches the person: one question,
+ * the server's. Approving gives no decision of its own, so the other gates still judge.
  */
 export declare function createGuidedGate(options: {
     runDir: string;

package/dist/core/hooks/guidedGate.js

@@ -15,8 +15,10 @@ const APPROVAL_TOOL = "mcp__approvals__request_human_approval";
  * 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.
+ * `destructiveHint`, asked on every call, so they're offered only yes, no and never (#78). An extension whose lock says `off`
+ * runs without asking. A tool whose server asks the person itself (`serverConfirmTools`, #77)
+ * isn't asked about too in guided mode, where that question reaches the person: one question,
+ * the server's. Approving gives no decision of its own, so the other gates still judge.
  */
 export function createGuidedGate(options) {
     const thisSession = new Set();
@@ -47,10 +49,14 @@ export function createGuidedGate(options) {
             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)
+        // Its server asks the person itself, and in guided mode its question reaches them (#77).
+        if (mode === "guided" && extension.serverConfirmTools?.includes(full)) {
+            await record("server-asks");
             return {};
-        if (thisSession.has(full))
+        }
+        const alwaysAsks = extension.confirmTools.includes(full) || (await options.isDestructive(full));
+        // A tool that always asks is asked on every call (#78): no kept "always", no "this session".
+        if (!alwaysAsks && (kept === "always" || thisSession.has(full)))
             return {};
         if (mode === "autonomous") {
             if (options.autonomous === "allow")
@@ -61,7 +67,8 @@ export function createGuidedGate(options) {
         if (batch && !alwaysAsks)
             return {};
         const answers = t().confirmAnswers;
-        const choices = [answers.yes, answers.session, ...(alwaysAsks ? [] : [answers.always]), answers.no, answers.never];
+        // For one that always asks, only what covers this call, or makes it stricter (#78).
+        const choices = alwaysAsks ? [answers.yes, answers.no, answers.never] : [answers.yes, answers.session, 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),

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
@@ -195,7 +197,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 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] }];
+            return [{ name: extension.name, scopeDir: installed.scopeDir, servers, confirmTools: [...(added[index]?.confirmTools ?? []), ...own], serverConfirmTools: added[index]?.serverConfirmTools ?? [] }];
         });
     const neverTools = (await Promise.all(guardedExtensions.map(async (extension) => {
         const confirm = (await readLock(extension.scopeDir).catch(() => ({})))[extension.name]?.confirm;
@@ -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/core/toolLabels.d.ts

@@ -22,7 +22,23 @@ export interface ToolLabel {
     label(input: Record<string, unknown>): string;
     /** How it counts in a folded group's summary, `[one, many]` with `{n}`: `["read {n} page", "read {n} pages"]`. */
     phrase?: ToolPhrase;
+    /**
+     * The line under it for its result, in the kit's language (#79): a string replaces the result's
+     * first line (written for the model, in English), `null` hides it, `undefined` keeps it. The
+     * model's result is never changed.
+     */
+    result?(result: ToolResult): string | null | undefined;
 }
+/** A tool call's result, as the chat shows it. */
+export interface ToolResult {
+    isError: boolean;
+    text: string;
+}
+/**
+ * Labels whose result line is hidden when the call succeeded (#79): for tools whose label already
+ * says what happened, so the person doesn't read the model's English under it. A failure still shows.
+ */
+export declare function quietResults(labels: ToolLabels): ToolLabels;
 /** Tools' labels by full name (`mcp__<server>__<tool>`): what the extensions of a session bring. */
 export type ToolLabels = Readonly<Record<string, ToolLabel>>;
 /**
@@ -33,6 +49,11 @@ export type ToolLabels = Readonly<Record<string, ToolLabel>>;
 export declare function withToolLabels(labels: () => ToolLabels | undefined, formatAction?: (toolName: string, toolInput: unknown) => string): (toolName: string, toolInput: unknown) => string;
 /** A `toolPhrase` that counts the tools in `labels()` with their phrase, and any other with `toolPhrase`. */
 export declare function withToolPhrases(labels: () => ToolLabels | undefined, toolPhrase?: (toolName: string) => ToolPhrase | undefined): (toolName: string) => ToolPhrase | undefined;
+/**
+ * A result formatter (the Ink chat's `formatResult`) that asks `formatResult` first, then the
+ * tools' labels (`ToolLabel.result`, #79): `undefined` from both keeps the result's first line.
+ */
+export declare function withToolResults(labels: () => ToolLabels | undefined, formatResult?: (toolName: string, result: ToolResult) => string | null | undefined): (toolName: string, result: ToolResult) => string | null | undefined;
 /** An agent's labels for its own tools: the tool's short name and input, to a label, or `undefined` for the kit's default. */
 export type ToolDescriber = (shortName: string, input: Record<string, unknown>) => string | undefined;
 /**

package/dist/core/toolLabels.js

@@ -71,6 +71,13 @@ function describeCore(shortName, input) {
             return undefined;
     }
 }
+/**
+ * Labels whose result line is hidden when the call succeeded (#79): for tools whose label already
+ * says what happened, so the person doesn't read the model's English under it. A failure still shows.
+ */
+export function quietResults(labels) {
+    return Object.fromEntries(Object.entries(labels).map(([tool, label]) => [tool, { ...label, result: (result) => (result.isError ? undefined : null) }]));
+}
 /**
  * A `formatAction` that shows the tools in `labels()` with their label, and any other with
  * `formatAction` (the kit's by default). `labels` is read on every call, so it can follow the
@@ -88,6 +95,16 @@ export function withToolLabels(labels, formatAction = createFriendlyToolLabel())
 export function withToolPhrases(labels, toolPhrase) {
     return (toolName) => labels()?.[toolName]?.phrase ?? toolPhrase?.(toolName);
 }
+/**
+ * A result formatter (the Ink chat's `formatResult`) that asks `formatResult` first, then the
+ * tools' labels (`ToolLabel.result`, #79): `undefined` from both keeps the result's first line.
+ */
+export function withToolResults(labels, formatResult) {
+    return (toolName, result) => {
+        const own = formatResult?.(toolName, result);
+        return own !== undefined ? own : labels()?.[toolName]?.result?.(result);
+    };
+}
 /**
  * Builds a `friendlyToolLabel(toolName, toolInput)` — `describe` lets the host agent
  * layer its own domain-specific cases (e.g. Playwright's browser_* tools) on top of this

package/dist/extensions/awareness/index.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { quietResults } from "../../core/toolLabels.js";
 import { agentKitVersion } from "../../core/version.js";
 import { awarenessToolLabels } from "./labels.js";
 import { createAwarenessServer } from "./tools.js";
@@ -44,7 +45,8 @@ export function awareness(options = {}) {
                 mcpServers: { awareness: createAwarenessServer(session, options.guide, catalog ? [createCatalogTool(config, session)] : []) },
                 promptSection: identityPromptSection(spec.identity, { catalog }),
                 readOnlyTools: ["mcp__awareness__about_me", ...(catalog ? ["mcp__awareness__extensions_catalog"] : [])],
-                toolLabels: awarenessToolLabels(),
+                // Their labels already say what happened: no English result line under them (#79).
+                toolLabels: quietResults(awarenessToolLabels()),
             };
         },
     };

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/extensions/knowledge/index.js

@@ -1,3 +1,4 @@
+import { quietResults } from "../../core/toolLabels.js";
 import { folderOf } from "../../core/extensions.js";
 import { createFileKnowledgeStore } from "./fileKnowledgeStore.js";
 import { knowledgeToolLabels } from "./labels.js";
@@ -27,7 +28,8 @@ export function knowledge(options) {
                 toolOnlyDirs: [{ dir: knowledgeDir, instead: "the knowledge_* tools" }],
                 readOnlyTools: ["mcp__knowledge__knowledge_index", "mcp__knowledge__knowledge_search", "mcp__knowledge__knowledge_read", "mcp__knowledge__knowledge_check"],
                 selfAskingTools: ["mcp__knowledge__knowledge_retire"],
-                toolLabels: knowledgeToolLabels(),
+                // Their labels already say what happened: no English result line under them (#79).
+                toolLabels: quietResults(knowledgeToolLabels()),
                 helpLines: [
                     "You keep a knowledge base (your memory across sessions). Its commands: `/knowledge:ingest` (learn the new or changed files of the sources folder), `/knowledge:query <question>` (answer from it), `/knowledge:lint` (check it and fix what's mechanical).",
                 ],

package/dist/extensions/memory/index.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { quietResults } from "../../core/toolLabels.js";
 import { folderOf } from "../../core/extensions.js";
 import { readConversation } from "../../core/runs.js";
 import { memoryToolLabels } from "./labels.js";
@@ -49,7 +50,8 @@ export function memory(options) {
                 toolOnlyDirs: [{ dir: memoryDir, instead: "its tools: recall, remember, forget" }],
                 readOnlyTools: ["mcp__memory__recall"],
                 hooks: { UserPromptSubmit: [{ hooks: [hear] }] },
-                toolLabels: memoryToolLabels(),
+                // Their labels already say what happened: no English result line under them (#79).
+                toolLabels: quietResults(memoryToolLabels()),
                 helpLines: [
                     "You keep a memory of the person across all their projects (how they like things done, who they are): `/memory:list` shows it, `/memory:forget <entry>` forgets an entry. Only what they tell you goes in it.",
                 ],

package/dist/extensions/sources/index.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { quietResults } from "../../core/toolLabels.js";
 import { folderOf } from "../../core/extensions.js";
 import { sourcesToolLabels } from "./labels.js";
 import { addSource } from "./sources.js";
@@ -29,7 +30,8 @@ export function sources(options) {
                 readOnlyDirs: [sourcesDir],
                 readOnlyTools: ["mcp__sourceFiles__list_sources", "mcp__sourceFiles__extract_text"],
                 selfAskingTools: ["mcp__sourceFiles__request_file", "mcp__sourceFiles__retire_source"],
-                toolLabels: sourcesToolLabels(),
+                // Their labels already say what happened: no English result line under them (#79).
+                toolLabels: quietResults(sourcesToolLabels()),
                 // For the host (a page's "add to the chest"): a file the person gave, with the same rules
                 // as the tools (never overwriting, a duplicate recognized) and the person as its origin.
                 api: {

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { allowAnyMcpTool } from "./core/mcpPermissions.js";
 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 { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withToolPhrases, withToolResults, quietResults, type ToolResult, type ToolDescriber, type ToolLabel, type ToolLabels, } from "./core/toolLabels.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";

package/dist/index.js

@@ -7,7 +7,7 @@ export { allowAnyMcpTool } from "./core/mcpPermissions.js";
 export { createPromptLoader } from "./core/promptTemplate.js";
 export { resolveClaudeAuth } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
-export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withToolPhrases, } from "./core/toolLabels.js";
+export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withToolPhrases, withToolResults, quietResults, } from "./core/toolLabels.js";
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode } from "./core/session.js";
 export { runQuery } from "./core/runner.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./extensions/knowledge/prompt.js";

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/dist/tui/ink/runChatInk.js

@@ -198,6 +198,7 @@ export async function runChatInk(options, tuiOptions = {}) {
         toolLabels: tuiOptions.toolLabels,
         formatAction: tuiOptions.formatAction,
         toolPhrase: tuiOptions.toolPhrase,
+        formatResult: tuiOptions.formatResult,
         ...(tuiOptions.openBrowser !== undefined ? { openBrowser: tuiOptions.openBrowser } : {}),
         promptSuggestions: tuiOptions.promptSuggestions ?? true,
         // The /resume list in place of the prompt.
@@ -221,7 +222,8 @@ export async function runChatInk(options, tuiOptions = {}) {
         formatAction: controller.formatAction,
         toolPhrase: controller.toolPhrase,
         toolDetail: tuiOptions.toolDetail,
-        formatResult: tuiOptions.formatResult,
+        // The agent's, then the labels' (#79).
+        formatResult: controller.formatResult,
         agentLabel: tuiOptions.agentLabel,
         width: () => liveWidth(stdout.columns),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.28.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/agent-kit-metadata.schema.json

@@ -35,7 +35,12 @@
       "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.",
+      "description": "Its tools that always ask the person in guided mode (short names), on every call, even inside a batch they approved, never offered \"this session\" or \"always\": what creates, edits or publishes in their account. Without it, its servers' destructiveHint says which.",
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "serverConfirmTools": {
+      "description": "Its tools whose server asks the person itself before acting, through MCP elicitation (short names): guided mode doesn't ask too while the person can be asked, so it's one question, the server's. Plan mode still stops them; autonomous mode still denies them unless the agent allows them.",
       "type": "array",
       "items": { "type": "string", "minLength": 1 }
     },
@@ -57,6 +62,11 @@
               "prefixItems": [{ "type": "string" }, { "type": "string" }],
               "minItems": 2,
               "maxItems": 2
+            },
+            "result": {
+              "description": "The line under the call when it succeeded, in this language, instead of the result's first line (written for the model, in English). A failure still shows its own.",
+              "type": "string",
+              "minLength": 1
             }
           }
         }

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" }
+      }
+    }
+  }
+}