@falkenslab/agent-kit 0.27.1 → 0.29.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). */
@@ -62,6 +64,13 @@ export interface ChatSettings {
      * state's `panel`, answered with `answer()`.
      */
     panels?: "view" | "state";
+    /**
+     * Signing in to an extension (#72): `true` (the default) opens the link in this computer's
+     * browser (`openBrowser()`: not over SSH or without a display), `false` never does, and a
+     * function opens it the host's way (Electron's `shell.openExternal`), saying whether it did.
+     * The link is shown either way, on a line of its own, for another computer.
+     */
+    openBrowser?: boolean | ((url: string) => Promise<boolean>);
 }
 /** One tool call in the transcript. */
 export interface TranscriptCall {
@@ -216,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). */
@@ -270,9 +280,10 @@ export declare function createChatController(options: Options | SessionOpener, s
      * person. The running session is untouched: it's there in a new conversation, or with `reopen()`.
      */
     /**
-     * Signs in to an installed extension's remote servers (#61): gives the person the links (never
-     * opens a browser), then says when the sign-in finishes. With `callbackUrl`, the address the
-     * browser ended on (from another computer), finishes it instead.
+     * Signs in to an installed extension's remote servers (#61): opens each link in this computer's
+     * browser as `openBrowser` says (#72) and shows it on a line of its own, for another computer,
+     * then says when the sign-in finishes. With `callbackUrl`, the address the browser ended on
+     * (from another computer), finishes it instead.
      */
     signInExtension(name: string, callbackUrl?: string): Promise<SignIn>;
     /** Signs out of an installed extension's remote servers (#61). */

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";
@@ -16,6 +16,7 @@ import { extensionOptionStates, listInstalled, removeExtension as removeInstalle
 import { extensionCatalog as readCatalog, installExtension as installFromCatalog, needsConfirmation, updateExtension as updateFromCatalog } from "../core/extensionCatalog.js";
 import { capHistory, loadHistory, saveHistory, slashCommandToken } from "./history.js";
 import { firstRun, openSession, runFolderOf, runLabel } from "./runs.js";
+import { openBrowser } from "../core/openBrowser.js";
 const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
 const DEFAULT_HISTORY_LIMIT = 100;
 const DEFAULT_PROMPT_LABEL = "\n> ";
@@ -38,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();
@@ -424,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). */
@@ -600,9 +603,10 @@ export async function createChatController(options, settings = {}) {
          * person. The running session is untouched: it's there in a new conversation, or with `reopen()`.
          */
         /**
-         * Signs in to an installed extension's remote servers (#61): gives the person the links (never
-         * opens a browser), then says when the sign-in finishes. With `callbackUrl`, the address the
-         * browser ended on (from another computer), finishes it instead.
+         * Signs in to an installed extension's remote servers (#61): opens each link in this computer's
+         * browser as `openBrowser` says (#72) and shows it on a line of its own, for another computer,
+         * then says when the sign-in finishes. With `callbackUrl`, the address the browser ended on
+         * (from another computer), finishes it instead.
          */
         async signInExtension(name, callbackUrl) {
             const auth = current.extensionAuth;
@@ -612,8 +616,13 @@ export async function createChatController(options, settings = {}) {
             else if (result.status === "signed-in")
                 notice(callbackUrl ? t().extensionSignedIn(name) : t().extensionAlreadySignedIn(name));
             else {
-                for (const link of result.links)
-                    notice(t().extensionSignInOpen(name, link.url));
+                const open = settings.openBrowser === false ? undefined : typeof settings.openBrowser === "function" ? settings.openBrowser : openBrowser;
+                for (const link of result.links) {
+                    const opened = open ? await open(link.url).catch(() => false) : false;
+                    notice(opened ? t().extensionSignInOpened(name) : t().extensionSignInOpen(name));
+                    // Alone on its line: a view shows it whole (a terminal link, #72), and it's copied whole.
+                    notice(link.url);
+                }
                 notice(t().extensionSignInPaste(name));
                 // Waits in the background: the person signs in in their browser, whenever they do.
                 void auth.connected(name, 5 * 60_000).then((done) => {

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/messages/de.js

@@ -53,7 +53,8 @@ export const de = {
     extensionLacks: (name, what) => `(${name}: ${what})`,
     extensionTalksTo: (name, hosts) => `(${name} spricht mit ${hosts}: was dein Agent dorthin sendet, verlässt diesen Computer)`,
     extensionNeedsSignIn: (name) => `${name} braucht deine Anmeldung: /extensions sign-in ${name}`,
-    extensionSignInOpen: (name, url) => `(zum Anmelden bei ${name} öffne ${url} : sobald du dort fertig bist, ist sie hier verbunden)`,
+    extensionSignInOpen: (name) => `(zum Anmelden bei ${name} öffne diesen Link; sobald du dort fertig bist, ist sie hier verbunden:)`,
+    extensionSignInOpened: (name) => `(Anmeldung bei ${name} in deinem Browser; sobald du dort fertig bist, ist sie hier verbunden. Der Link, für einen anderen Browser:)`,
     extensionSignInPaste: (name) => `(auf einem anderen Computer? Füge die Adresse ein, bei der der Browser landet: /extensions sign-in ${name} <diese Adresse>)`,
     extensionSignedIn: (name) => `(bei ${name} angemeldet: ihre Werkzeuge sind bereit)`,
     extensionSignInWaiting: (name) => `(warte noch auf die Anmeldung bei ${name}; /extensions sign-in ${name} gibt den Link erneut)`,

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

@@ -73,7 +73,9 @@ export interface Messages {
     /** In /extensions: a running extension whose remote server needs the person to sign in. */
     extensionNeedsSignIn(name: string): string;
     /** The link to sign in to an extension's remote server. */
-    extensionSignInOpen(name: string, url: string): string;
+    /** Before the sign-in link, on its own line next (#72): when the browser couldn't be opened, and when it was. */
+    extensionSignInOpen(name: string): string;
+    extensionSignInOpened(name: string): string;
     /** How to finish signing in from another computer. */
     extensionSignInPaste(name: string): string;
     extensionSignedIn(name: string): string;

package/dist/core/messages/en.js

@@ -53,7 +53,8 @@ export const en = {
     extensionLacks: (name, what) => `(${name} ${what})`,
     extensionTalksTo: (name, hosts) => `(${name} talks to ${hosts}: what your agent sends there leaves this computer)`,
     extensionNeedsSignIn: (name) => `${name} needs you to sign in: /extensions sign-in ${name}`,
-    extensionSignInOpen: (name, url) => `(to sign in to ${name}, open ${url} : when you're done there, it's connected here)`,
+    extensionSignInOpen: (name) => `(to sign in to ${name}, open this link; when you're done there, it's connected here:)`,
+    extensionSignInOpened: (name) => `(signing in to ${name} in your browser; when you're done there, it's connected here. The link, for another browser:)`,
     extensionSignInPaste: (name) => `(on another computer? Paste the address the browser ends on: /extensions sign-in ${name} <that address>)`,
     extensionSignedIn: (name) => `(signed in to ${name}: its tools are ready)`,
     extensionSignInWaiting: (name) => `(still waiting for the sign-in to ${name}; /extensions sign-in ${name} gives the link again)`,

package/dist/core/messages/es.js

@@ -53,7 +53,8 @@ export const es = {
     extensionLacks: (name, what) => `(${name}: ${what})`,
     extensionTalksTo: (name, hosts) => `(${name} habla con ${hosts}: lo que tu agente le envíe sale de este ordenador)`,
     extensionNeedsSignIn: (name) => `${name} necesita que inicies sesión: /extensions sign-in ${name}`,
-    extensionSignInOpen: (name, url) => `(para iniciar sesión en ${name}, abre ${url} : cuando termines allí, queda conectada aquí)`,
+    extensionSignInOpen: (name) => `(para iniciar sesión en ${name}, abre este enlace; cuando termines allí, queda conectada aquí:)`,
+    extensionSignInOpened: (name) => `(iniciando sesión en ${name} en tu navegador; cuando termines allí, queda conectada aquí. El enlace, para otro navegador:)`,
     extensionSignInPaste: (name) => `(¿en otro ordenador? Pega la dirección en la que acaba el navegador: /extensions sign-in ${name} <esa dirección>)`,
     extensionSignedIn: (name) => `(sesión iniciada en ${name}: sus herramientas están listas)`,
     extensionSignInWaiting: (name) => `(sigo esperando el inicio de sesión en ${name}; /extensions sign-in ${name} vuelve a dar el enlace)`,

package/dist/core/messages/fr.js

@@ -53,7 +53,8 @@ export const fr = {
     extensionLacks: (name, what) => `(${name} : ${what})`,
     extensionTalksTo: (name, hosts) => `(${name} échange avec ${hosts} : ce que votre agent y envoie quitte cet ordinateur)`,
     extensionNeedsSignIn: (name) => `${name} a besoin que vous vous connectiez : /extensions sign-in ${name}`,
-    extensionSignInOpen: (name, url) => `(pour vous connecter à ${name}, ouvrez ${url} : une fois terminé là-bas, elle est connectée ici)`,
+    extensionSignInOpen: (name) => `(pour vous connecter à ${name}, ouvrez ce lien ; une fois terminé là-bas, elle est connectée ici :)`,
+    extensionSignInOpened: (name) => `(connexion à ${name} dans votre navigateur ; une fois terminé là-bas, elle est connectée ici. Le lien, pour un autre navigateur :)`,
     extensionSignInPaste: (name) => `(sur un autre ordinateur ? Collez l'adresse où le navigateur arrive : /extensions sign-in ${name} <cette adresse>)`,
     extensionSignedIn: (name) => `(connecté à ${name} : ses outils sont prêts)`,
     extensionSignInWaiting: (name) => `(toujours en attente de la connexion à ${name} ; /extensions sign-in ${name} redonne le lien)`,

package/dist/core/session.js

@@ -195,7 +195,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;

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/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";
@@ -52,6 +52,7 @@ export { createSaveToSourcesServer, sourcesPromptSection, type SourceToolsOption
 export { runChatTui, type ChatTuiOptions } from "./tui/chatTui.js";
 export type { SessionOpener } from "./chat/runs.js";
 export { createChatController, type ChatController, type ChatSettings, type ChatState, type ChatEvent, type ChatPanel, type ChatQuestion, type TranscriptEntry, type TranscriptCall, type NoticeTone, } from "./chat/chatController.js";
+export { openBrowser, canOpenBrowser } from "./core/openBrowser.js";
 export { createConsoleRenderer, type ConsoleRenderer, type ConsoleRendererOptions } from "./tui/consoleRenderer.js";
 export { runChatInk, type InkChatOptions, type HeaderInfo } from "./tui/ink/runChatInk.js";
 export type { ToolPhrase, ToolDetail, ResultFormatter } from "./tui/ink/toolGroup.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";
@@ -53,6 +53,7 @@ export { createManualLoginServer } from "./core/tools/manualLogin.js";
 export { createSaveToSourcesServer, sourcesPromptSection } from "./extensions/sources/tools.js";
 export { runChatTui } from "./tui/chatTui.js";
 export { createChatController, } from "./chat/chatController.js";
+export { openBrowser, canOpenBrowser } from "./core/openBrowser.js";
 export { createConsoleRenderer } from "./tui/consoleRenderer.js";
 export { runChatInk } from "./tui/ink/runChatInk.js";
 export { createProgressView } from "./tui/ink/progressView.js";

package/dist/tui/chatTui.d.ts

@@ -4,6 +4,7 @@ import type { AgentEvent } from "../core/runner.js";
 import { type Theme } from "./theme.js";
 import type { ToolLabels } from "../core/toolLabels.js";
 import { type SessionOpener } from "../chat/runs.js";
+import { type ChatSettings } from "../chat/chatController.js";
 export { capHistory, loadHistory, saveHistory, slashCommandToken } from "../chat/history.js";
 /** Options of the chats (`runChatTui()`, and `runChatInk()` through `InkChatOptions`). */
 export interface ChatTuiOptions {
@@ -14,6 +15,8 @@ export interface ChatTuiOptions {
      * own domain-specific tools (Playwright's `browser_*`, etc.).
      */
     formatAction?: (toolName: string, input: unknown) => string;
+    /** Signing in to an extension: whether its link opens in this computer's browser (the default), or how (see `ChatSettings.openBrowser`, #72). */
+    openBrowser?: ChatSettings["openBrowser"];
     /** Printed once before the first prompt, if given. */
     welcomeMessage?: string;
     /** Shown before the cursor at each prompt. */

package/dist/tui/chatTui.js

@@ -8,6 +8,7 @@ import { applyTheme } from "./theme.js";
 import { createConsoleRenderer } from "./consoleRenderer.js";
 import { runDate } from "../chat/runs.js";
 import { createChatController } from "../chat/chatController.js";
+import { linkedNotice } from "./hyperlink.js";
 export { capHistory, loadHistory, saveHistory, slashCommandToken } from "../chat/history.js";
 const DEFAULT_PROMPT_LABEL = "\n> ";
 const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
@@ -75,6 +76,7 @@ export async function runChatTui(options, tuiOptions = {}) {
         modeControl: tuiOptions.modeControl,
         toolLabels: tuiOptions.toolLabels,
         formatAction: tuiOptions.formatAction,
+        ...(tuiOptions.openBrowser !== undefined ? { openBrowser: tuiOptions.openBrowser } : {}),
         // Nothing here shows them.
         promptSuggestions: false,
         // /resume: a numbered list, and a number typed.
@@ -131,7 +133,8 @@ export async function runChatTui(options, tuiOptions = {}) {
                     renderer.render(event.event);
                 return;
             case "notice":
-                writeLine(toned(event.text, event.tone));
+                // An address alone (a sign-in link) as a terminal link (#72).
+                writeLine(toned(linkedNotice(event.text), event.tone));
                 return;
             case "turn-start":
                 renderer.startTurn();

package/dist/tui/hyperlink.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Terminal hyperlinks (OSC 8, #72): a long address the full-screen chat wraps stays one link,
+ * since every row it's cut into opens it whole (`wrap-ansi` reopens the link on each row).
+ */
+/**
+ * Whether the terminal shows OSC 8 links, from what it says about itself: Windows Terminal,
+ * VS Code's, iTerm2, WezTerm, Konsole, a recent VTE (GNOME's), DomTerm. `FORCE_HYPERLINK=1` or `0`
+ * decides. Elsewhere none: a terminal that doesn't know the sequence may print it.
+ */
+export declare function supportsHyperlinks(env?: NodeJS.ProcessEnv, isTTY?: boolean): boolean;
+/** `text` as a link to `url` (OSC 8). */
+export declare function hyperlink(url: string, text?: string): string;
+/** A notice that is an address alone (a sign-in link, #72) as a link when the terminal shows them; any other text as it is. */
+export declare function linkedNotice(text: string, linked?: boolean): string;

package/dist/tui/hyperlink.js

@@ -0,0 +1,28 @@
+/**
+ * Terminal hyperlinks (OSC 8, #72): a long address the full-screen chat wraps stays one link,
+ * since every row it's cut into opens it whole (`wrap-ansi` reopens the link on each row).
+ */
+/**
+ * Whether the terminal shows OSC 8 links, from what it says about itself: Windows Terminal,
+ * VS Code's, iTerm2, WezTerm, Konsole, a recent VTE (GNOME's), DomTerm. `FORCE_HYPERLINK=1` or `0`
+ * decides. Elsewhere none: a terminal that doesn't know the sequence may print it.
+ */
+export function supportsHyperlinks(env = process.env, isTTY = process.stdout.isTTY === true) {
+    if (env.FORCE_HYPERLINK !== undefined)
+        return env.FORCE_HYPERLINK !== "0";
+    if (!isTTY)
+        return false;
+    if (env.WT_SESSION || env.KONSOLE_VERSION || env.DOMTERM)
+        return true;
+    if (["vscode", "iTerm.app", "WezTerm"].includes(env.TERM_PROGRAM ?? ""))
+        return true;
+    return Number(env.VTE_VERSION ?? 0) >= 5000;
+}
+/** `text` as a link to `url` (OSC 8). */
+export function hyperlink(url, text = url) {
+    return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+/** A notice that is an address alone (a sign-in link, #72) as a link when the terminal shows them; any other text as it is. */
+export function linkedNotice(text, linked = supportsHyperlinks()) {
+    return linked && /^https?:\/\/\S+$/.test(text) ? hyperlink(text) : text;
+}

package/dist/tui/ink/runChatInk.js

@@ -6,6 +6,7 @@ import { Select } from "@inkjs/ui";
 import { getInteractionPort, setInteractionPort } from "../../core/interaction.js";
 import { runChatTui } from "../chatTui.js";
 import { createChatController } from "../../chat/chatController.js";
+import { linkedNotice } from "../hyperlink.js";
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.js";
 import { applyLanguage } from "../language.js";
@@ -197,6 +198,8 @@ 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.
         pick: (title, choices) => input.pick(title, choices),
@@ -219,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),
     });
@@ -241,7 +245,8 @@ export async function runChatInk(options, tuiOptions = {}) {
                 model.note(userLine(event.text), "user");
                 return;
             case "notice":
-                model.writeLine(toned(event.text, event.tone));
+                // An address alone (a sign-in link) as a terminal link, whole however it wraps (#72).
+                model.writeLine(toned(linkedNotice(event.text), event.tone));
                 return;
             case "turn-start":
                 input.setSuggestion(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.27.1",
+  "version": "0.29.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
             }
           }
         }