@falkenslab/agent-kit 0.14.0 → 0.15.0

package/README.md

@@ -1,110 +1,110 @@
-<h1>
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-readme-dark.svg">
-    <img src="docs/assets/logo-readme.svg" alt="agent-kit" height="64">
-  </picture>
-</h1>
-
-[![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)
-[![npm downloads](https://img.shields.io/npm/dm/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
-[![types](https://img.shields.io/npm/types/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
-[![node](https://img.shields.io/node/v/@falkenslab/agent-kit)](https://nodejs.org/)
-[![license](https://img.shields.io/npm/l/@falkenslab/agent-kit)](LICENSE)
-[![docs](https://img.shields.io/badge/docs-falkenslab.github.io%2Fagent--kit-4453b8)](https://falkenslab.github.io/agent-kit/)
-
-A foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (human oversight, safety, memory and a good terminal interface), so each concrete agent only has to write what belongs to its own domain: what it knows how to do, with which tools, and how it talks.
-
-## What an agent built with it can do
-
-- **Work at different levels of oversight.** Autonomous, guided (it asks for permission before anything that can't be undone or that other people will see) or step by step (it asks before every action), and a plan mode where it only reads and plans until you let it act. Within the same conversation you can switch among guided, step by step and plan.
-- **Ask a person for help.** It asks for approvals, or stops so someone can do something by hand, such as signing in to a website. It can be answered from the keyboard or from another program driving it, for example a desktop app.
-- **Remember between sessions.** It keeps its own knowledge base, a small wiki of notes that grows with every session, and keeps the original documents you give it or that it downloads untouched. Each conversation stays in the project's folder, so you can pick it up again with `--continue` (the latest one) or `/resume` (any of them).
-- **Speak your language.** Its interface comes in English, Spanish, French or German, the system's by default or the one you ask for with `--language=fr`, and it answers in that language unless you write to it in another one.
-- **Delegate to subagents safely.** Only to the ones it declares, always waiting for their result, and without the main agent being able to slip past its own limits through them.
-- **Stay within limits.** It only reads and writes in the folders that belong to it, and never in protected files, such as one holding passwords.
-- **Use external tools.** MCP servers of its own or of the project, and skills and commands organized in plugins.
-- **Leave a trail.** It records every action and the whole conversation, with secrets hidden.
-- **Look the way you want.** The terminal's colors come from a theme by roles (the agent's replies, tool results, the focused option, borders…): pass only the ones you want to change, as a color name, a hex or a function.
-- **Chat in a terminal the way Claude Code does.** Full screen, with the reply written live and its markdown already formatted, the tools it uses summed up in one line (Ctrl+O unfolds it), panels for approvals, history and search, a suggestion for the next message, pasted blocks, file mentions with `@`, mouse selection (right-click to copy), and the agent's status in the tab and in the Windows taskbar.
-- **Also work without a terminal.** The same foundation runs inside a desktop app or a server, which bring their own interface.
-
-## Examples
-
-### Captain Whiskers
-
-[Captain Whiskers](./examples/captain-whiskers) is a toy agent to see the kit in action: a retired pirate cat who tells jokes in the terminal, in your language. It starts full screen with its logo and has a small crew of subagents: one looks for new jokes on the web, another rates them before they're told, and a third tells the time with a tool of the captain's own. It lets you try the different levels of oversight and is the best starting point for an agent of your own. Its README explains how to run it.
-
-![Captain Whiskers in Windows Terminal: its logo at the top, the conversation in the middle and the framed prompt at the bottom, with a suggestion for the next message](docs/assets/captain-whiskers.png)
-
-### teacher-agent
-
-[teacher-agent](https://github.com/falkenslab/teacher-agent) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
-
-Oversight, memory, safety and the chat come from the kit; teacher-agent brings what it knows about Moodle and driving the browser.
-
-## Installation
-
-```
-npm install @falkenslab/agent-kit
-```
-
-To try changes to the kit without publishing them, point to a local clone with `"file:../agent-kit"` in your `package.json` and build it with `npm run build` after each change.
-
-Requires Node.js 20 or later.
-
-## A minimal agent
-
-An agent only describes what belongs to it (who it is, which MCP servers, skills and subagents it has) and picks a level of oversight; the kit sets up the session and the chat:
-
-```ts
-import path from "node:path";
-import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
-
-// The only part specific to the agent: who it is and what it has.
-const spec: AgentSpec<BaseSessionConfig> = {
-  buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
-  buildMcpServers: () => ({}), // its own MCP servers, if any
-  pluginRoots: () => [], // folders with skills and commands
-  buildSubagents: () => undefined, // subagents, if it delegates to any
-};
-
-await ensureClaudeAuth(); // offers to create a Claude token if it finds none
-
-const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
-
-// Each run gets a folder of its own under .run/ (keep it out of git): its log, its
-// transcript and the conversation, to pick it up again with --continue or /resume.
-await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
-  runsDir: path.resolve(".run"),
-  header: { title: "My agent" },
-  mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
-  fullscreen: true,
-  theme: { toolResult: "gray", selection: "#ffb86c" }, // only the colors you want to change
-});
-```
-
-Save it as `agent.ts` in a project with the kit and `tsx` installed and `"type": "module"` in its `package.json`, and run it with `npx tsx agent.ts`. Captain Whiskers is this same skeleton with more pieces: skills, subagents and its logo.
-
-## Documentation
-
-The full documentation is at **[falkenslab.github.io/agent-kit](https://falkenslab.github.io/agent-kit/)**: a tutorial, guides for every part of the kit (modes, human in the loop, security, tools, subagents, the knowledge base, the terminal UI, runs, languages, themes, hosts without a terminal), recipes, and an API reference generated from the source, for each released version.
-
-For whoever works on the kit itself, the specification in [`.minispec/`](./.minispec/README.md) explains how each part is built and why, including the SDK behaviors checked by hand that motivate several of its safeguards.
-
-## Development
-
-| Command | What it does |
-| --- | --- |
-| `npm run build` | Builds the kit into `dist/` |
-| `npm run typecheck` | Checks the types without building |
-| `npm run lint` | Checks the code style |
-| `npm test` | Runs all the tests |
-| `npm run docs:install` | Installs the documentation site's dependencies (once) |
-| `npm run docs:start` | Serves the documentation site locally, reloading on changes |
-| `npm run docs:build` | Builds the documentation site (fails on broken links) |
-
-To run a single test file:
-
-```
-npx tsx --test test/tui/promptErrors.test.ts
-```
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-readme-dark.svg">
+    <img src="docs/assets/logo-readme.svg" alt="agent-kit" height="64">
+  </picture>
+</h1>
+
+[![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+[![npm downloads](https://img.shields.io/npm/dm/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+[![types](https://img.shields.io/npm/types/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+[![node](https://img.shields.io/node/v/@falkenslab/agent-kit)](https://nodejs.org/)
+[![license](https://img.shields.io/npm/l/@falkenslab/agent-kit)](LICENSE)
+[![docs](https://img.shields.io/badge/docs-falkenslab.github.io%2Fagent--kit-4453b8)](https://falkenslab.github.io/agent-kit/)
+
+A foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (human oversight, safety, memory and a good terminal interface), so each concrete agent only has to write what belongs to its own domain: what it knows how to do, with which tools, and how it talks.
+
+## What an agent built with it can do
+
+- **Work at different levels of oversight.** Autonomous, guided (it asks for permission before anything that can't be undone or that other people will see) or step by step (it asks before every action), and a plan mode where it only reads and plans until you let it act. Within the same conversation you can switch among guided, step by step and plan.
+- **Ask a person for help.** It asks for approvals, or stops so someone can do something by hand, such as signing in to a website. It can be answered from the keyboard or from another program driving it, for example a desktop app.
+- **Remember between sessions.** It keeps its own knowledge base, a small wiki of notes that grows with every session, and keeps the original documents you give it or that it downloads untouched. Each conversation stays in the project's folder, so you can pick it up again with `--continue` (the latest one) or `/resume` (any of them).
+- **Speak your language.** Its interface comes in English, Spanish, French or German, the system's by default or the one you ask for with `--language=fr`, and it answers in that language unless you write to it in another one.
+- **Delegate to subagents safely.** Only to the ones it declares, always waiting for their result, and without the main agent being able to slip past its own limits through them.
+- **Stay within limits.** It only reads and writes in the folders that belong to it, and never in protected files, such as one holding passwords.
+- **Use external tools.** MCP servers of its own or of the project, and skills and commands organized in plugins.
+- **Leave a trail.** It records every action and the whole conversation, with secrets hidden.
+- **Look the way you want.** The terminal's colors come from a theme by roles (the agent's replies, tool results, the focused option, borders…): pass only the ones you want to change, as a color name, a hex or a function.
+- **Chat in a terminal the way Claude Code does.** Full screen, with the reply written live and its markdown already formatted, the tools it uses shown in as much detail as the agent chooses (each call with its result, the calls alone, or one line per group; Ctrl+O unfolds them), panels for approvals, history and search, a suggestion for the next message, pasted blocks, file mentions with `@`, mouse selection (right-click to copy), and the agent's status in the tab and in the Windows taskbar.
+- **Also work without a terminal.** The same foundation runs inside a desktop app or a server, which bring their own interface.
+
+## Examples
+
+### Captain Whiskers
+
+[Captain Whiskers](./examples/captain-whiskers) is a toy agent to see the kit in action: a retired pirate cat who tells jokes in the terminal, in your language. It starts full screen with its logo and has a small crew of subagents: one looks for new jokes on the web, another rates them before they're told, and a third tells the time with a tool of the captain's own. It lets you try the different levels of oversight and is the best starting point for an agent of your own. Its README explains how to run it.
+
+![Captain Whiskers in Windows Terminal: its logo at the top, the conversation in the middle and the framed prompt at the bottom, with a suggestion for the next message](docs/assets/captain-whiskers.png)
+
+### teacher-agent
+
+[teacher-agent](https://github.com/falkenslab/teacher-agent) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
+
+Oversight, memory, safety and the chat come from the kit; teacher-agent brings what it knows about Moodle and driving the browser.
+
+## Installation
+
+```
+npm install @falkenslab/agent-kit
+```
+
+To try changes to the kit without publishing them, point to a local clone with `"file:../agent-kit"` in your `package.json` and build it with `npm run build` after each change.
+
+Requires Node.js 20 or later.
+
+## A minimal agent
+
+An agent only describes what belongs to it (who it is, which MCP servers, skills and subagents it has) and picks a level of oversight; the kit sets up the session and the chat:
+
+```ts
+import path from "node:path";
+import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
+
+// The only part specific to the agent: who it is and what it has.
+const spec: AgentSpec<BaseSessionConfig> = {
+  buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
+  buildMcpServers: () => ({}), // its own MCP servers, if any
+  pluginRoots: () => [], // folders with skills and commands
+  buildSubagents: () => undefined, // subagents, if it delegates to any
+};
+
+await ensureClaudeAuth(); // offers to create a Claude token if it finds none
+
+const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
+
+// Each run gets a folder of its own under .run/ (keep it out of git): its log, its
+// transcript and the conversation, to pick it up again with --continue or /resume.
+await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
+  runsDir: path.resolve(".run"),
+  header: { title: "My agent" },
+  mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
+  fullscreen: true,
+  theme: { toolResult: "gray", selection: "#ffb86c" }, // only the colors you want to change
+});
+```
+
+Save it as `agent.ts` in a project with the kit and `tsx` installed and `"type": "module"` in its `package.json`, and run it with `npx tsx agent.ts`. Captain Whiskers is this same skeleton with more pieces: skills, subagents and its logo.
+
+## Documentation
+
+The full documentation is at **[falkenslab.github.io/agent-kit](https://falkenslab.github.io/agent-kit/)**: a tutorial, guides for every part of the kit (modes, human in the loop, security, tools, subagents, the knowledge base, the terminal UI, runs, languages, themes, hosts without a terminal), recipes, and an API reference generated from the source, for each released version.
+
+For whoever works on the kit itself, the specification in [`.minispec/`](./.minispec/README.md) explains how each part is built and why, including the SDK behaviors checked by hand that motivate several of its safeguards.
+
+## Development
+
+| Command | What it does |
+| --- | --- |
+| `npm run build` | Builds the kit into `dist/` |
+| `npm run typecheck` | Checks the types without building |
+| `npm run lint` | Checks the code style |
+| `npm test` | Runs all the tests |
+| `npm run docs:install` | Installs the documentation site's dependencies (once) |
+| `npm run docs:start` | Serves the documentation site locally, reloading on changes |
+| `npm run docs:build` | Builds the documentation site (fails on broken links) |
+
+To run a single test file:
+
+```
+npx tsx --test test/tui/promptErrors.test.ts
+```

package/dist/core/messages/de.js

@@ -70,6 +70,7 @@ export const de = {
     otherTools: ["hat {n} Werkzeug verwendet", "hat {n} Werkzeuge verwendet"],
     noOutput: "(keine Ausgabe)",
     error: "Fehler",
+    toolFailed: "Konnte nicht abgeschlossen werden",
     moreResultLines: (count) => `(+${count} ${plural(count, "Zeile", "Zeilen")})`,
     earlierCalls: (count) => `… ${count} frühere`,
     labels: {

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

@@ -55,6 +55,8 @@ export interface Messages {
     otherTools: ToolPhrase;
     noOutput: string;
     error: string;
+    /** A failed tool call when results are hidden (`toolDetail: "calls"`): no tool output, just that it failed. */
+    toolFailed: string;
     moreResultLines(count: number): string;
     earlierCalls(count: number): string;
     labels: {

package/dist/core/messages/en.js

@@ -69,6 +69,7 @@ export const en = {
     otherTools: ["used {n} tool", "used {n} tools"],
     noOutput: "(no output)",
     error: "error",
+    toolFailed: "Couldn't complete it",
     moreResultLines: (count) => `(+${count} ${plural(count, "line", "lines")})`,
     earlierCalls: (count) => `… ${count} earlier`,
     labels: {

package/dist/core/messages/es.js

@@ -70,6 +70,7 @@ export const es = {
     otherTools: ["usó {n} herramienta", "usó {n} herramientas"],
     noOutput: "(sin salida)",
     error: "error",
+    toolFailed: "No se pudo completar",
     moreResultLines: (count) => `(+${count} ${plural(count, "línea", "líneas")})`,
     earlierCalls: (count) => `… ${count} ${plural(count, "anterior", "anteriores")}`,
     labels: {

package/dist/core/messages/fr.js

@@ -70,6 +70,7 @@ export const fr = {
     otherTools: ["a utilisé {n} outil", "a utilisé {n} outils"],
     noOutput: "(aucune sortie)",
     error: "erreur",
+    toolFailed: "Impossible de terminer",
     moreResultLines: (count) => `(+${count} ${plural(count, "ligne", "lignes")})`,
     earlierCalls: (count) => `… ${count} ${plural(count, "précédent", "précédents")}`,
     labels: {

package/dist/index.d.ts

@@ -32,7 +32,7 @@ export { runChatTui, type ChatTuiOptions } from "./tui/chatTui.js";
 export type { SessionOpener } from "./tui/runs.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 } from "./tui/ink/toolGroup.js";
+export type { ToolPhrase, ToolDetail, ResultFormatter } from "./tui/ink/toolGroup.js";
 export type { RenderApproval } from "./tui/ink/SessionView.js";
 export { createProgressView, type ProgressView, type ProgressViewOptions } from "./tui/ink/progressView.js";
 export { runWizard, type WizardStep, type SelectStep, type InputStep, type PasswordStep, type ConfirmStep, type WizardAnswers, type WizardOptions, } from "./tui/ink/wizard.js";

package/dist/tui/ink/SessionView.js

@@ -161,12 +161,17 @@ function FullscreenSession({ session, checkpoint, renderApproval, mode, header,
         if (!historyRef.current || end === start)
             return null;
         const box = framePosition(historyRef.current);
-        const firstY = box.y + historyHeight - (end - start); // the rows are bottom-aligned
+        // Measured now, not `historyHeight`: that state is set by an effect after the layout, so
+        // a click on the first frames would find the rows where they were before it.
+        const height = measureElement(historyRef.current).height;
+        const firstY = box.y + height - (end - start); // the rows are bottom-aligned
         let offset = y - firstY;
-        if (offset < 0 || offset >= end - start) {
+        // Rows that don't fit are clipped above the box, not clickable.
+        const firstShown = Math.max(0, box.y - firstY);
+        if (offset < firstShown || offset >= end - start) {
             if (!clamp)
                 return null;
-            offset = Math.min(end - start - 1, Math.max(0, offset));
+            offset = Math.min(end - start - 1, Math.max(firstShown, offset));
         }
         return { row: start + offset, col: Math.max(0, x - box.x) };
     }

package/dist/tui/ink/progressView.d.ts

@@ -2,12 +2,16 @@ import type { Mode } from "../../core/agentSpec.js";
 import { type ConsoleRenderer, type ConsoleRendererOptions } from "../consoleRenderer.js";
 import { type SessionModel } from "./sessionModel.js";
 import { type RenderApproval } from "./SessionView.js";
-import type { ToolPhrase } from "./toolGroup.js";
+import type { ResultFormatter, ToolDetail, ToolPhrase } from "./toolGroup.js";
 import { type Theme } from "../theme.js";
 /** Options of `createProgressView()`. */
 export interface ProgressViewOptions extends Omit<ConsoleRendererOptions, "output"> {
     /** How one of the agent's own tools counts in a folded group's summary (see `InkChatOptions.toolPhrase`). */
     toolPhrase?: (toolName: string) => ToolPhrase | undefined;
+    /** How much of the tool calls shows (see `InkChatOptions.toolDetail`); "full" if not given. */
+    toolDetail?: ToolDetail;
+    /** The result line under a tool call (see `InkChatOptions.formatResult`). */
+    formatResult?: ResultFormatter;
     /** Replaces the default preview in the approval and manual-intervention panels. */
     renderApproval?: RenderApproval;
     /** Shown in the status bar. */

package/dist/tui/ink/runChatInk.d.ts

@@ -4,7 +4,7 @@ import { type ModeControl } from "../../core/session.js";
 import { type ChatTuiOptions } from "../chatTui.js";
 import { type SessionOpener } from "../runs.js";
 import { type RenderApproval } from "./SessionView.js";
-import type { ToolPhrase } from "./toolGroup.js";
+import type { ResultFormatter, ToolDetail, ToolPhrase } from "./toolGroup.js";
 import { type HeaderInfo } from "./header.js";
 export type { HeaderInfo } from "./header.js";
 /** Options of `runChatInk()`: the chat's options plus the Ink-only ones. */
@@ -45,6 +45,21 @@ export interface InkChatOptions extends ChatTuiOptions {
      * counts as "used {n} tools".
      */
     toolPhrase?: (toolName: string) => ToolPhrase | undefined;
+    /**
+     * How much of the tool calls shows: `"full"` (the default), every call with its result
+     * line; `"calls"`, the calls without their results, a failed one with a short line in the
+     * kit's language instead of the tool's error; `"summary"`, one line per group ("Read 2
+     * files, ran 1 shell command"). Ctrl+O unfolds any of them into the full view. For an
+     * audience that doesn't need the tools' raw output. The session log is the same whatever
+     * the level.
+     */
+    toolDetail?: ToolDetail;
+    /**
+     * The line under a tool call for its result, e.g. a friendly one for an MCP tool whose
+     * output is written for the model: a string replaces the kit's (the result's first line),
+     * `null` hides it, `undefined` keeps it. Shown wherever results are (`"full"`, or unfolded).
+     */
+    formatResult?: ResultFormatter;
     /**
      * The session's mode control (`buildSessionOptions()` returns it): the status bar shows the
      * current mode, Shift+Tab switches between the modes it allows ("guided", "interactive"

package/dist/tui/ink/runChatInk.js

@@ -210,6 +210,8 @@ export async function runChatInk(options, tuiOptions = {}) {
     const model = createSessionModel({
         formatAction: tuiOptions.formatAction,
         toolPhrase: tuiOptions.toolPhrase,
+        toolDetail: tuiOptions.toolDetail,
+        formatResult: tuiOptions.formatResult,
         agentLabel: tuiOptions.agentLabel,
         onWrite: mirror,
         width: () => liveWidth(stdout.columns),

package/dist/tui/ink/sessionModel.d.ts

@@ -1,12 +1,12 @@
 import type { AgentEvent, SessionUsage } from "../../core/runner.js";
 import { type ConsoleRenderer } from "../consoleRenderer.js";
-import { type ToolPhrase } from "./toolGroup.js";
+import { type ResultFormatter, type ToolDetail, type ToolPhrase } from "./toolGroup.js";
 export interface HistoryItem {
     id: number;
     text: string;
     /** What it is: the view draws the human's lines as a bar, and the spacing follows it. */
     kind?: OutputKind;
-    /** A folded group of tool calls: the lines it unfolds into with Ctrl+O. */
+    /** A group of tool calls: the lines it unfolds into with Ctrl+O (`text` is the folded view). */
     expanded?: string[];
 }
 /**
@@ -30,7 +30,7 @@ export interface SessionSnapshot {
     activity: string | null;
     /** Label of the latest action taken inside a subagent in this turn. */
     subagentActivity: string | null;
-    /** Tool calls shown one by one with their results (the default); Ctrl+O folds them into a summary line. */
+    /** Tool groups unfolded into every call with its result (Ctrl+O toggles it); folded, they show as `toolDetail` says. */
     expanded: boolean;
     turns: number;
     usage: SessionUsage | null;
@@ -41,6 +41,10 @@ export interface SessionModelOptions {
     formatAction?: (toolName: string, toolInput: unknown) => string;
     /** How a tool counts in a folded group's summary ("read 2 files"); built-in tools have their own. */
     toolPhrase?: (toolName: string) => ToolPhrase | undefined;
+    /** How much of the tool calls shows until Ctrl+O (see `ToolDetail`); "full" if not given. */
+    toolDetail?: ToolDetail;
+    /** The result line under a tool call (see `ResultFormatter`). */
+    formatResult?: ResultFormatter;
     agentLabel?: string;
     /** Called with everything the console renderer writes, e.g. to mirror a session log. */
     onWrite?: (text: string) => void;

package/dist/tui/ink/sessionModel.js

@@ -29,6 +29,7 @@ const isBlank = (line) => stripAnsi(line).trim() === "";
  */
 export function createSessionModel(options = {}) {
     const formatAction = options.formatAction ?? createFriendlyToolLabel();
+    const toolDetail = options.toolDetail ?? "full";
     const width = () => Math.max(20, options.width?.() ?? 80);
     const listeners = new Set();
     let nextId = 0;
@@ -40,7 +41,7 @@ export function createSessionModel(options = {}) {
         turnStartedAt: null,
         activity: null,
         subagentActivity: null,
-        expanded: true,
+        expanded: toolDetail === "full",
         turns: 0,
         usage: null,
         contextPercent: null,
@@ -146,7 +147,15 @@ export function createSessionModel(options = {}) {
             return;
         const calls = group;
         group = null;
-        push([groupLine(calls)], "action", { expanded: toolGroupExpanded(calls, width()) });
+        push([folded(calls).join("\n")], "action", { expanded: unfolded(calls) });
+    }
+    /** A group with every call and its result: "full", or any level unfolded with Ctrl+O. */
+    function unfolded(calls) {
+        return toolGroupExpanded(calls, width(), { formatResult: options.formatResult });
+    }
+    /** A group as its level shows it folded: the calls without results, or one summary line. */
+    function folded(calls) {
+        return toolDetail === "calls" ? toolGroupExpanded(calls, width(), { results: false }) : [groupLine(calls)];
     }
     function groupLine(calls) {
         return INDENT + ui.dim(fitWidth(toolGroupSummary(calls, options.toolPhrase), width() - INDENT.length));
@@ -161,7 +170,7 @@ export function createSessionModel(options = {}) {
         let rows = liveRows;
         let kind = liveRows.length > 0 ? "agent" : null;
         if (group) {
-            rows = snapshot.expanded ? toolGroupExpanded(group, width()) : [groupLine(group)];
+            rows = snapshot.expanded ? unfolded(group) : folded(group);
             kind = "action";
         }
         const live = rows.join("\n");

package/dist/tui/ink/toolGroup.d.ts

@@ -13,6 +13,27 @@ export interface ToolCall {
 }
 /** How a tool counts in a group's summary: the phrase for one call and for several, "{n}" standing for the count. */
 export type { ToolPhrase };
+/**
+ * How much of its tool calls a chat shows: `"full"`, every call with its result line;
+ * `"calls"`, the calls without their results (a failed call says so in one short line);
+ * `"summary"`, one line per group. Ctrl+O unfolds any of them into the full view.
+ */
+export type ToolDetail = "full" | "calls" | "summary";
+/**
+ * The line shown under a tool call for its result: a string replaces the kit's (plain text,
+ * drawn in the result's color, or the error color if it failed), `null` hides it, and
+ * `undefined` keeps the kit's (the result's first line).
+ */
+export type ResultFormatter = (toolName: string, result: {
+    isError: boolean;
+    text: string;
+}) => string | null | undefined;
+/** How `toolGroupExpanded()` draws the results. */
+export interface ResultOptions {
+    /** Show the result lines (the default); without them a failed call shows a short failure line. */
+    results?: boolean;
+    formatResult?: ResultFormatter;
+}
 /**
  * A folded group's one line, as in the Claude Code CLI: "Read 2 files, ran 1 shell
  * command". Calls to the same kind of tool are counted together, in the order they first
@@ -32,6 +53,6 @@ export declare function resultSummary(result: {
 /**
  * The calls one by one: each behind a `●`, then after `⎿` the calls a subagent made (the
  * latest few, dim) and the result in one line (a subagent's answer with its markdown
- * rendered), or "…" while it runs.
+ * rendered), or "…" while it runs. Without `options.results`, only a failure's short line.
  */
-export declare function toolGroupExpanded(calls: readonly ToolCall[], width: number): string[];
+export declare function toolGroupExpanded(calls: readonly ToolCall[], width: number, options?: ResultOptions): string[];

package/dist/tui/ink/toolGroup.js

@@ -43,20 +43,33 @@ export function resultSummary(result, markdown = false) {
     // would cancel a dim around it.
     return ui.toolResult(markdown ? stripAnsi(renderMarkdown(first, 1000)[0] ?? first) : first) + more;
 }
+/** The line under a call for its result, or null for none. */
+function resultLine(call, { results = true, formatResult }) {
+    if (!call.result)
+        return results ? ui.dim("…") : null;
+    if (!results)
+        return call.result.isError ? ui.error(t().toolFailed) : null;
+    const custom = formatResult?.(call.toolName, call.result);
+    if (custom === null)
+        return null;
+    if (custom !== undefined)
+        return call.result.isError ? ui.error(custom) : ui.toolResult(custom);
+    return resultSummary(call.result, SUBAGENT_TOOLS.has(call.toolName));
+}
 /**
  * The calls one by one: each behind a `●`, then after `⎿` the calls a subagent made (the
  * latest few, dim) and the result in one line (a subagent's answer with its markdown
- * rendered), or "…" while it runs.
+ * rendered), or "…" while it runs. Without `options.results`, only a failure's short line.
  */
-export function toolGroupExpanded(calls, width) {
+export function toolGroupExpanded(calls, width, options = {}) {
     return calls.flatMap((call) => {
         const children = call.children ?? [];
         const shown = children.slice(-MAX_CHILDREN);
-        const result = call.result ? fitWidth(resultSummary(call.result, SUBAGENT_TOOLS.has(call.toolName)), width - 5) : ui.dim("…");
+        const result = resultLine(call, options);
         const under = [
             ...(children.length > shown.length ? [ui.dim(t().earlierCalls(children.length - shown.length))] : []),
             ...shown.map((label) => fitWidth(ui.dim(`· ${label}`), width - 5)),
-            result,
+            ...(result === null ? [] : [fitWidth(result, width - 5)]),
         ];
         return [
             `${ui.toolBullet("●")} ${fitWidth(ui.toolLabel(call.label), width - 2)}`,

package/package.json

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