@falkenslab/agent-kit 0.13.1 → 0.15.0

package/README.md

@@ -1,17 +1,22 @@
-# agent-kit
+<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-d77757)](https://falkenslab.github.io/agent-kit/)
+[![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). Within the same conversation you can switch from guided to step by step and back.
+- **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.
@@ -20,7 +25,7 @@ A foundation for building AI agents on top of the [Claude Agent SDK](https://www
 - **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.
+- **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
@@ -72,7 +77,7 @@ const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
 await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
   runsDir: path.resolve(".run"),
   header: { title: "My agent" },
-  mode: config.mode, // Shift+Tab switches between guided and step by step
+  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
 });

package/dist/core/agentSpec.d.ts

@@ -3,7 +3,8 @@ import type { AgentDefinition as SdkSubagentDefinition, McpServerConfig, Setting
  * The human-supervision spectrum every agent built on this kit shares, independent of
  * domain: "interactive" pauses before every single action, "guided" only pauses before a
  * hard-to-undo/visible-to-others action, "autonomous" has no human-in-the-loop channel at
- * all. See session.ts's buildSessionOptions() for exactly what each mode changes.
+ * all, and "plan" only reads and plans: nothing is changed until the human leaves it (see
+ * hooks/planGate.ts). See session.ts's buildSessionOptions() for exactly what each mode changes.
  *
  * Deliberately orthogonal to whether the session is a one-shot run or a multi-turn chat
  * (that's a matter of which entry point the caller uses — a single `query()` call vs.
@@ -12,7 +13,7 @@ import type { AgentDefinition as SdkSubagentDefinition, McpServerConfig, Setting
  * different system-prompt template) should track that as its own domain field on its
  * config type, not conflate it with `Mode`.
  */
-export type Mode = "interactive" | "guided" | "autonomous";
+export type Mode = "interactive" | "guided" | "autonomous" | "plan";
 /**
  * The minimum a config object needs to drive `buildSessionOptions()` — a concrete agent's
  * own config type (e.g. a `Config`) extends this with whatever domain fields
@@ -159,4 +160,25 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
         checkpointLines: string[];
         checkpointQuestion?: string;
     };
+    /**
+     * What the agent may still do in "plan" mode, where it only reads and plans (see
+     * hooks/planGate.ts). Without it, the agent can read, search, ask a human and delegate,
+     * writes nothing and presents its plan in its reply.
+     */
+    planMode?: PlanModeSpec<TConfig>;
+}
+/** The domain's part of "plan" mode: which files hold the plan and which of its own tools only read. */
+export interface PlanModeSpec<TConfig extends BaseSessionConfig = BaseSessionConfig> {
+    /**
+     * Whether `filePath` (absolute) is a plan file Write/Edit may touch in plan mode, e.g.
+     * `drafts/<slug>/plan.md`. It must also be writable under the file scope (`knowledgeDir`
+     * or `extraWritableDirs`), which still applies.
+     */
+    isPlanFile?(filePath: string, config: TConfig): boolean;
+    /**
+     * Whether one of the agent's own MCP tools (`mcp__<server>__<tool>`) only reads, so plan
+     * mode lets it run. Every MCP tool it doesn't vouch for is denied there: a forgotten tool
+     * can't change anything.
+     */
+    isReadOnlyTool?(toolName: string, input: Record<string, unknown>): boolean;
 }

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

@@ -0,0 +1,23 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+/** What plan mode lets through besides reading: see createPlanGate(). */
+export interface PlanScope {
+    /** Base for relative paths: the session's cwd. */
+    projectDir: string;
+    /** Whether Write/Edit may touch this file (absolute) in plan mode. */
+    isPlanFile?(filePath: string): boolean;
+    /** Whether one of the agent's own MCP tools only reads. */
+    isReadOnlyTool?(toolName: string, input: Record<string, unknown>): boolean;
+}
+/**
+ * The reason to deny `toolName` with `input` in plan mode, or `undefined` to let it through.
+ * Anything not known to only read is denied, so a tool nobody thought of can't change
+ * anything while the human reviews the plan.
+ */
+export declare function checkPlanScope(scope: PlanScope, toolName: string, input: Record<string, unknown>): string | undefined;
+/**
+ * PreToolUse hook for "plan" mode: the agent only reads and plans (see checkPlanScope()).
+ * Registered for every session that can be in plan mode and deciding only while `isActive()`
+ * says it is; otherwise it gives no decision, so the call goes on as if it weren't there.
+ * It's the kit's own gate, not the SDK's `permissionMode: "plan"` (ADR-023).
+ */
+export declare function createPlanGate(scope: PlanScope, isActive: () => boolean): HookCallback;

package/dist/core/hooks/planGate.js

@@ -0,0 +1,52 @@
+import path from "node:path";
+/** Built-in tools that only read, search, load a skill or delegate (a subagent's own calls come through this gate too). */
+const READING_TOOLS = new Set(["Read", "Glob", "Grep", "WebFetch", "WebSearch", "Skill", "Agent"]);
+/** The kit's own MCP tools that only ask a human: approvals and manual intervention. */
+const ASKING_SERVERS = ["mcp__approvals__", "mcp__manualLogin__"];
+/** Why a call is denied in plan mode, and what the model should do instead. */
+const denial = "Plan mode: nothing can be changed until the user leaves plan mode. Keep reading and researching, then present the plan; the user switches out of plan mode when they want it carried out.";
+/**
+ * The reason to deny `toolName` with `input` in plan mode, or `undefined` to let it through.
+ * Anything not known to only read is denied, so a tool nobody thought of can't change
+ * anything while the human reviews the plan.
+ */
+export function checkPlanScope(scope, toolName, input) {
+    if (READING_TOOLS.has(toolName))
+        return undefined;
+    if (ASKING_SERVERS.some((prefix) => toolName.startsWith(prefix)))
+        return undefined;
+    if (toolName === "Write" || toolName === "Edit") {
+        const target = typeof input.file_path === "string" && input.file_path !== "" ? path.resolve(scope.projectDir, input.file_path) : undefined;
+        if (target && scope.isPlanFile?.(target))
+            return undefined;
+        return scope.isPlanFile
+            ? `Plan mode: "${String(input.file_path)}" isn't a plan file, and nothing else can be written until the user leaves plan mode. Write the plan to its plan file.`
+            : denial;
+    }
+    if (toolName.startsWith("mcp__") && scope.isReadOnlyTool?.(toolName, input))
+        return undefined;
+    return denial;
+}
+/**
+ * PreToolUse hook for "plan" mode: the agent only reads and plans (see checkPlanScope()).
+ * Registered for every session that can be in plan mode and deciding only while `isActive()`
+ * says it is; otherwise it gives no decision, so the call goes on as if it weren't there.
+ * It's the kit's own gate, not the SDK's `permissionMode: "plan"` (ADR-023).
+ */
+export function createPlanGate(scope, isActive) {
+    return async (input) => {
+        if (!isActive())
+            return {};
+        const pre = input;
+        const reason = checkPlanScope(scope, pre.tool_name, (pre.tool_input ?? {}));
+        if (!reason)
+            return {};
+        return {
+            hookSpecificOutput: {
+                hookEventName: pre.hook_event_name,
+                permissionDecision: "deny",
+                permissionDecisionReason: reason,
+            },
+        };
+    };
+}

package/dist/core/messages/de.js

@@ -1,5 +1,5 @@
 const plural = (count, one, many) => (count === 1 ? one : many);
-const MODES = { autonomous: "autonom", guided: "geführt", interactive: "interaktiv" };
+const MODES = { autonomous: "autonom", guided: "geführt", interactive: "interaktiv", plan: "Plan" };
 export const de = {
     thinking: "Denkt nach…",
     escToInterrupt: "Esc zum Unterbrechen",
@@ -35,6 +35,7 @@ export const de = {
         "Esc unterbrechen  ·  Strg+C unterbrechen oder beenden  ·  Bild↑/Bild↓ oder Mausrad scrollen  ·  Strg+Ende ganz nach unten",
         "Ziehen zum Markieren, Rechtsklick zum Kopieren (Vollbild)",
         "/resume ein früheres Gespräch fortsetzen  ·  --continue beim Start setzt das letzte fort",
+        "/plan Planmodus ein- oder ausschalten: der Agent liest und plant nur, bis du ihn verlässt",
     ],
     moreLines: (count) => `… (${count} weitere Zeilen)`,
     proceed: "Möchtest du fortfahren?",
@@ -69,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

@@ -34,6 +34,7 @@ export const en = {
         "Esc interrupt  ·  Ctrl+C interrupt or exit  ·  PgUp/PgDn or wheel scroll  ·  Ctrl+End bottom",
         "Drag to select, right-click to copy (full screen)",
         "/resume resume an earlier conversation  ·  --continue on the command line resumes the latest one",
+        "/plan plan mode on or off: the agent only reads and plans until you leave it",
     ],
     moreLines: (count) => `… (${count} more lines)`,
     proceed: "Do you want to proceed?",
@@ -68,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

@@ -1,5 +1,5 @@
 const plural = (count, one, many) => (count === 1 ? one : many);
-const MODES = { autonomous: "autónomo", guided: "guiado", interactive: "interactivo" };
+const MODES = { autonomous: "autónomo", guided: "guiado", interactive: "interactivo", plan: "plan" };
 export const es = {
     thinking: "Pensando…",
     escToInterrupt: "esc para interrumpir",
@@ -35,6 +35,7 @@ export const es = {
         "Esc interrumpir  ·  Ctrl+C interrumpir o salir  ·  RePág/AvPág o rueda desplazarse  ·  Ctrl+Fin abajo del todo",
         "Arrastrar para seleccionar, clic derecho para copiar (pantalla completa)",
         "/resume retomar una conversación anterior  ·  --continue al arrancar retoma la última",
+        "/plan activar o desactivar el modo plan: el agente solo lee y planifica hasta que salgas",
     ],
     moreLines: (count) => `… (${count} líneas más)`,
     proceed: "¿Quieres continuar?",
@@ -69,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

@@ -1,5 +1,5 @@
 const plural = (count, one, many) => (count === 1 ? one : many);
-const MODES = { autonomous: "autonome", guided: "guidé", interactive: "interactif" };
+const MODES = { autonomous: "autonome", guided: "guidé", interactive: "interactif", plan: "plan" };
 export const fr = {
     thinking: "Réflexion…",
     escToInterrupt: "échap pour interrompre",
@@ -35,6 +35,7 @@ export const fr = {
         "Échap interrompre  ·  Ctrl+C interrompre ou quitter  ·  PgPréc/PgSuiv ou molette défiler  ·  Ctrl+Fin tout en bas",
         "Glisser pour sélectionner, clic droit pour copier (plein écran)",
         "/resume reprendre une conversation précédente  ·  --continue au démarrage reprend la dernière",
+        "/plan activer ou quitter le mode plan : l'agent lit et planifie seulement jusqu'à ce que vous en sortiez",
     ],
     moreLines: (count) => `… (${count} lignes de plus)`,
     proceed: "Voulez-vous continuer ?",
@@ -69,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/core/runs.js

@@ -151,6 +151,8 @@ export function entryText(entry) {
             .map((part) => part.text ?? "")
             .join("");
     }
+    // The kit's own notes to the model (a plan-mode switch) go before the human's words.
+    text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>\s*/g, "");
     // Slash commands and the CLI's own notes arrive as tagged text, not as the human's words.
     if (!text.trim() || /^\s*<[a-z-]+>/.test(text))
         return null;

package/dist/core/session.d.ts

@@ -15,8 +15,8 @@ import { type RunFolder } from "./runs.js";
  * fields on `BaseSessionConfig`.
  *
  * The per-mode behavioral differences (whether the approval/manual-intervention tools
- * exist, whether the interactive step gate hook runs) all fall out of `config.mode`
- * alone.
+ * exist, whether the interactive step gate or the plan gate decides) all fall out of
+ * `config.mode` and the session's `ModeControl` alone.
  *
  * `options.run` keeps the SDK's transcript of the conversation in that run folder (see
  * runs.ts's createRunStore()) and, when it has a session already, resumes it: the chat
@@ -33,22 +33,35 @@ export declare function buildSessionOptions<TConfig extends BaseSessionConfig>(c
     language: Language;
 }>;
 /**
- * The supervision mode of a running session. Only "guided" and "interactive" can switch into
- * each other: they share the same tools (the approval tool) and the step gate is registered
- * in both, asking only in "interactive". "autonomous" has no approval tool at all, and a tool
- * can't appear or vanish mid-session, so a session that starts autonomous stays autonomous,
- * and one that doesn't can't become autonomous. The system prompt keeps the mode it was
- * built with.
+ * The supervision mode of a running session. "guided", "interactive" and "plan" switch into
+ * one another: they share the same tools (the approval tool), and the step gate and the plan
+ * gate are registered in all three, deciding only in their own mode. "autonomous" has no
+ * approval tool at all, and a tool can't appear or vanish mid-session, so a session that
+ * starts autonomous stays autonomous, and one that doesn't can't become autonomous. The
+ * system prompt keeps the mode it was built with, so entering or leaving plan mode is told
+ * to the model with the next message instead (`takeNotice()`).
  */
 export interface ModeControl {
     readonly mode: Mode;
-    /** The modes this session can be in; fewer than two means it can't switch. */
+    /** The modes this session can be in, in Shift+Tab's order; fewer than two means it can't switch. */
     readonly switchable: readonly Mode[];
     /** Switches to `next` if this session allows it; returns whether it did. */
     set(next: Mode): boolean;
+    /**
+     * The note telling the model it entered or left plan mode, once per change it hasn't been
+     * told about yet; `undefined` otherwise. `createInputQueue({ modeControl })` puts it before
+     * the next message; a caller with its own queue prepends it itself.
+     */
+    takeNotice?(): string | undefined;
 }
 /** A `ModeControl` starting at `initial` (`buildSessionOptions()` returns one for its session). */
 export declare function createModeControl(initial: Mode): ModeControl;
+/**
+ * What the chats' `/plan` does: switches `control` into plan mode, or, when it's already
+ * there, back to the mode it was entered from ("guided" if it started in plan mode). Returns
+ * the new mode, or `null` when this session can't be in plan mode (an autonomous one).
+ */
+export declare function togglePlanMode(control: ModeControl): Mode | null;
 /**
  * User message queue backed by a single long-lived generator, for any multi-turn
  * (chat-shaped) caller of `query()`.
@@ -59,8 +72,13 @@ export declare function createModeControl(initial: Mode): ModeControl;
  * "ProcessTransport is not ready for writing". A real multi-turn conversation needs a
  * single generator that never finishes on its own: messages get pushed into it with
  * `push()` and it's only explicitly closed with `end()` when leaving the chat.
+ *
+ * With `modeControl`, each message goes after the note on a plan-mode switch the model
+ * hasn't been told about yet (`ModeControl.takeNotice()`).
  */
-export declare function createInputQueue(): {
+export declare function createInputQueue(options?: {
+    modeControl?: ModeControl;
+}): {
     push: (text: string) => void;
     end: () => void;
     iterable: AsyncIterable<SDKUserMessage>;

package/dist/core/session.js

@@ -5,6 +5,7 @@ import { createSubagentBashGate } from "./hooks/subagentBashGate.js";
 import { createSubagentTypeGate } from "./hooks/subagentTypeGate.js";
 import { createSubagentForegroundGate } from "./hooks/subagentForegroundGate.js";
 import { createFileScopeGate } from "./hooks/fileScopeGate.js";
+import { createPlanGate } from "./hooks/planGate.js";
 import { createHumanApprovalServer } from "./tools/humanApproval.js";
 import { createManualLoginServer } from "./tools/manualLogin.js";
 import { createSaveToSourcesServer } from "./tools/saveToSources.js";
@@ -25,8 +26,8 @@ import { createRunStore } from "./runs.js";
  * fields on `BaseSessionConfig`.
  *
  * The per-mode behavioral differences (whether the approval/manual-intervention tools
- * exist, whether the interactive step gate hook runs) all fall out of `config.mode`
- * alone.
+ * exist, whether the interactive step gate or the plan gate decides) all fall out of
+ * `config.mode` and the session's `ModeControl` alone.
  *
  * `options.run` keeps the SDK's transcript of the conversation in that run folder (see
  * runs.ts's createRunStore()) and, when it has a session already, resumes it: the chat
@@ -166,6 +167,21 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 // Registered wherever the approval tool is, and asking only while the current mode is
                 // "interactive": a guided session can switch to interactive and back (ModeControl).
                 ...(includeApprovalTool ? [{ hooks: [createStepGate(runDir, () => modeControl.mode === "interactive")] }] : []),
+                // Likewise for "plan", which any non-autonomous session can switch into: the agent
+                // only reads and plans while it's on (hooks/planGate.ts).
+                ...(includeApprovalTool
+                    ? [
+                        {
+                            hooks: [
+                                createPlanGate({
+                                    projectDir: config.projectDir,
+                                    ...(spec.planMode?.isPlanFile ? { isPlanFile: (filePath) => spec.planMode.isPlanFile(filePath, config) } : {}),
+                                    ...(spec.planMode?.isReadOnlyTool ? { isReadOnlyTool: spec.planMode.isReadOnlyTool } : {}),
+                                }, () => modeControl.mode === "plan"),
+                            ],
+                        },
+                    ]
+                    : []),
                 ...(includeSubagentTools
                     ? [
                         { hooks: [createSubagentTypeGate(allowedSubagentTypes)] },
@@ -189,7 +205,10 @@ function skillList(skills, includeKnowledgeBase) {
 /** A `ModeControl` starting at `initial` (`buildSessionOptions()` returns one for its session). */
 export function createModeControl(initial) {
     let current = initial;
-    const switchable = initial === "autonomous" ? ["autonomous"] : ["guided", "interactive"];
+    // The mode the model was last told about: a session starting in plan mode tells it with
+    // the first message, since the system prompt doesn't say.
+    let told = initial === "plan" ? undefined : initial;
+    const switchable = initial === "autonomous" ? ["autonomous"] : ["guided", "interactive", "plan"];
     return {
         get mode() {
             return current;
@@ -201,8 +220,40 @@ export function createModeControl(initial) {
             current = next;
             return true;
         },
+        takeNotice() {
+            const before = told;
+            told = current;
+            if (current === "plan" && before !== "plan")
+                return PLAN_MODE_ENTERED;
+            if (current !== "plan" && before === "plan")
+                return PLAN_MODE_LEFT;
+            return undefined;
+        },
     };
 }
+// The mode each session was in when `/plan` took it into plan mode, to go back to.
+const modeBeforePlan = new WeakMap();
+/**
+ * What the chats' `/plan` does: switches `control` into plan mode, or, when it's already
+ * there, back to the mode it was entered from ("guided" if it started in plan mode). Returns
+ * the new mode, or `null` when this session can't be in plan mode (an autonomous one).
+ */
+export function togglePlanMode(control) {
+    if (!control.switchable.includes("plan"))
+        return null;
+    if (control.mode === "plan") {
+        const back = modeBeforePlan.get(control) ?? "guided";
+        control.set(back);
+        return back;
+    }
+    modeBeforePlan.set(control, control.mode);
+    control.set("plan");
+    return "plan";
+}
+// What the model reads on a plan-mode switch, in English like the rest of what it reads
+// (ADR-019); tagged so a resumed conversation doesn't show it as the human's words (runs.ts).
+const PLAN_MODE_ENTERED = "<system-reminder>The user switched to plan mode. Only read, research and plan: nothing can be changed (files, tools that modify something) until they switch out of it. When the plan is ready, present it and wait for them.</system-reminder>";
+const PLAN_MODE_LEFT = "<system-reminder>The user left plan mode: you can carry out the plan now.</system-reminder>";
 /**
  * User message queue backed by a single long-lived generator, for any multi-turn
  * (chat-shaped) caller of `query()`.
@@ -213,8 +264,11 @@ export function createModeControl(initial) {
  * "ProcessTransport is not ready for writing". A real multi-turn conversation needs a
  * single generator that never finishes on its own: messages get pushed into it with
  * `push()` and it's only explicitly closed with `end()` when leaving the chat.
+ *
+ * With `modeControl`, each message goes after the note on a plan-mode switch the model
+ * hasn't been told about yet (`ModeControl.takeNotice()`).
  */
-export function createInputQueue() {
+export function createInputQueue(options = {}) {
     const pending = [];
     let wake = null;
     let ended = false;
@@ -236,7 +290,8 @@ export function createInputQueue() {
     }
     return {
         push(text) {
-            pending.push(text);
+            const notice = options.modeControl?.takeNotice?.();
+            pending.push(notice ? `${notice}\n\n${text}` : text);
             wake?.();
             wake = null;
         },

package/dist/index.d.ts

@@ -6,8 +6,8 @@ export { createPromptLoader } from "./core/promptTemplate.js";
 export { resolveClaudeAuth, type ClaudeAuthConfig } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
 export { createFriendlyToolLabel, truncate, truncatePath, type ToolDescriber, } from "./core/toolLabels.js";
-export type { Mode, BaseSessionConfig, AgentSpec } from "./core/agentSpec.js";
-export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, type ModeControl } from "./core/session.js";
+export type { Mode, BaseSessionConfig, AgentSpec, PlanModeSpec } from "./core/agentSpec.js";
+export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode, type ModeControl } from "./core/session.js";
 export { runQuery, type AgentEvent, type AgentRun, type SessionUsage, type ContextUsage } from "./core/runner.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./core/knowledge.js";
 export { resolveLanguage, detectLanguage, SUPPORTED_LANGUAGES, type Language, type LanguageSources, type ResolvedLanguage, } from "./core/language.js";
@@ -21,6 +21,7 @@ export { createSubagentBashGate } from "./core/hooks/subagentBashGate.js";
 export { createSubagentTypeGate } from "./core/hooks/subagentTypeGate.js";
 export { createSubagentForegroundGate } from "./core/hooks/subagentForegroundGate.js";
 export { createFileScopeGate, checkFileScope, type FileScope } from "./core/hooks/fileScopeGate.js";
+export { createPlanGate, checkPlanScope, type PlanScope } from "./core/hooks/planGate.js";
 export { askForDecision, askForManualIntervention } from "./core/hooks/humanInput.js";
 export { setInteractionPort, getInteractionPort, type InteractionPort, type ApprovalPrompt } from "./core/interaction.js";
 export { terminalInteractionPort, setSharedReadline, getSharedReadline } from "./tui/terminalInteraction.js";
@@ -31,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/index.js

@@ -8,7 +8,7 @@ export { createPromptLoader } from "./core/promptTemplate.js";
 export { resolveClaudeAuth } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
 export { createFriendlyToolLabel, truncate, truncatePath, } from "./core/toolLabels.js";
-export { buildSessionOptions, createInputQueue, createDeferred, createModeControl } from "./core/session.js";
+export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode } from "./core/session.js";
 export { runQuery } from "./core/runner.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./core/knowledge.js";
 export { resolveLanguage, detectLanguage, SUPPORTED_LANGUAGES, } from "./core/language.js";
@@ -23,6 +23,7 @@ export { createSubagentBashGate } from "./core/hooks/subagentBashGate.js";
 export { createSubagentTypeGate } from "./core/hooks/subagentTypeGate.js";
 export { createSubagentForegroundGate } from "./core/hooks/subagentForegroundGate.js";
 export { createFileScopeGate, checkFileScope } from "./core/hooks/fileScopeGate.js";
+export { createPlanGate, checkPlanScope } from "./core/hooks/planGate.js";
 export { askForDecision, askForManualIntervention } from "./core/hooks/humanInput.js";
 export { setInteractionPort, getInteractionPort } from "./core/interaction.js";
 export { terminalInteractionPort, setSharedReadline, getSharedReadline } from "./tui/terminalInteraction.js";

package/dist/tui/chatTui.d.ts

@@ -1,4 +1,5 @@
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
+import { type ModeControl } from "../core/session.js";
 import { type AgentEvent } from "../core/runner.js";
 import { type Theme } from "./theme.js";
 import { type SessionOpener } from "./runs.js";
@@ -72,6 +73,13 @@ export interface ChatTuiOptions {
      * conversation, tool results included and not redacted: keep it out of version control.
      */
     runsDir?: string;
+    /**
+     * The session's mode control (`buildSessionOptions()` returns it): `/plan` switches into
+     * plan mode and back (an autonomous session can't switch), and entering or leaving plan
+     * mode is told to the model with the next message. With a session opener, the one it
+     * returns is used instead.
+     */
+    modeControl?: ModeControl;
     /**
      * Colors for the kit's roles (see `Theme`), on top of the kit's defaults: only the roles
      * given change, e.g. `{ toolResult: "yellow", selection: "#00ff00" }`. One theme per

package/dist/tui/chatTui.js

@@ -3,7 +3,7 @@ import { stdin, stdout } from "node:process";
 import { createWriteStream } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { createInputQueue } from "../core/session.js";
+import { createInputQueue, togglePlanMode } from "../core/session.js";
 import { runQuery } from "../core/runner.js";
 import { listRuns, readConversation } from "../core/runs.js";
 import { isSharedQuestionActive, setSharedReadline } from "./terminalInteraction.js";
@@ -116,7 +116,8 @@ export async function runChatTui(options, tuiOptions = {}) {
         throw new Error("runChatTui(): a session opener needs `runsDir`.");
     // The session in use: with runs, the run's folder, rebuilt on /resume.
     let current = opener && runsDir ? await openSession(opener, await firstRun(runsDir)) : { options: options, run: null };
-    let queue = createInputQueue();
+    const modeControl = () => current.modeControl ?? tuiOptions.modeControl;
+    let queue = createInputQueue({ modeControl: modeControl() });
     let run = runQuery(queue.iterable, current.options);
     let events = run.events[Symbol.asyncIterator]();
     const historyLimit = tuiOptions.historyLimit ?? DEFAULT_HISTORY_LIMIT;
@@ -257,7 +258,7 @@ export async function runChatTui(options, tuiOptions = {}) {
         run.close();
         current = await openSession(opener, await runFolderOf(summary));
         openLog();
-        queue = createInputQueue();
+        queue = createInputQueue({ modeControl: modeControl() });
         run = runQuery(queue.iterable, current.options);
         events = run.events[Symbol.asyncIterator]();
         knownCommandTokens = null;
@@ -299,6 +300,13 @@ export async function runChatTui(options, tuiOptions = {}) {
                 await resume();
                 continue;
             }
+            // Plan mode on and off (the Ink chat also has Shift+Tab); the line says where it is now.
+            if (line.toLowerCase() === "/plan") {
+                const control = modeControl();
+                const next = control ? togglePlanMode(control) : null;
+                writeLine(ui.dim(next ? `⏵⏵ ${t().mode(next)}` : t().modeLocked(control?.mode)));
+                continue;
+            }
             // A line that *looks* like a slash command but matches nothing registered (a typo,
             // an unnamespaced plugin command, ...) would otherwise reach the model as literal
             // text with no special handling — confirmed empirically (captain-whiskers'

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

@@ -9,9 +9,13 @@ export type RenderApproval = (prompt: ApprovalPrompt) => ReactNode;
 /**
  * The preview's lines, capped so the whole live area stays shorter than the terminal: Ink
  * clears the entire screen (scrollback included) to redraw anything taller, and a step-gate
- * preview carries the tool's parameters, which can be a whole file.
+ * preview carries the tool's parameters, which can be a whole file. `reservedRows` is what
+ * the rest of the screen needs besides the preview; full screen adds its pinned header, or
+ * the panel's options and the status bar end up below the terminal's last row. With `width`
+ * (the panel's inner width) the cap counts screen rows, not lines: a long summary line takes
+ * several.
  */
-export declare function previewLines(lines: readonly string[], terminalRows: number | undefined): string[];
+export declare function previewLines(lines: readonly string[], terminalRows: number | undefined, reservedRows?: number, width?: number): string[];
 export declare function statusText(mode: Mode | undefined, turns: number, usage: SessionUsage | null, extra?: {
     contextPercent?: number | null;
     modeSwitchable?: boolean;

package/dist/tui/ink/SessionView.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import wrapAnsi from "wrap-ansi";
 import { useEffect, useReducer, useRef, useState, useSyncExternalStore } from "react";
 import { Box, measureElement, Static, Text, useInput, useStdout } from "ink";
 import { Select } from "@inkjs/ui";
@@ -18,17 +19,30 @@ const decisionOptions = () => [
 ];
 const manualOptions = () => [{ label: `1. ${t().doneContinue}`, value: "continue" }];
 const DECISION_KEYS = { "1": "y", "2": "n", "3": "q", y: "y", n: "n", q: "q" };
+/**
+ * The rows a checkpoint panel's preview leaves to everything else: the panel's own frame
+ * (borders, title, question, options: 8 rows), the status bar and a little room.
+ */
+const PANEL_RESERVED_ROWS = 12;
+/** The panel's border and horizontal padding, on both sides. */
+const PANEL_FRAME_COLUMNS = 4;
 /**
  * The preview's lines, capped so the whole live area stays shorter than the terminal: Ink
  * clears the entire screen (scrollback included) to redraw anything taller, and a step-gate
- * preview carries the tool's parameters, which can be a whole file.
+ * preview carries the tool's parameters, which can be a whole file. `reservedRows` is what
+ * the rest of the screen needs besides the preview; full screen adds its pinned header, or
+ * the panel's options and the status bar end up below the terminal's last row. With `width`
+ * (the panel's inner width) the cap counts screen rows, not lines: a long summary line takes
+ * several.
  */
-export function previewLines(lines, terminalRows) {
-    const all = lines.flatMap((line) => line.split("\n"));
-    const max = Math.max(3, (terminalRows || 24) - 12);
+export function previewLines(lines, terminalRows, reservedRows = PANEL_RESERVED_ROWS, width) {
+    const all = lines
+        .flatMap((line) => line.split("\n"))
+        .flatMap((line) => (width ? wrapAnsi(line, Math.max(1, width), { hard: true, trim: false }).split("\n") : [line]));
+    const max = Math.max(3, (terminalRows || 24) - reservedRows);
     return all.length <= max ? all : [...all.slice(0, max - 1), ui.dim(t().moreLines(all.length - max + 1))];
 }
-function CheckpointPanel({ checkpoint, renderApproval }) {
+function CheckpointPanel({ checkpoint, renderApproval, reservedRows, width, }) {
     const decision = checkpoint.kind === "decision";
     useInput((input) => {
         const key = input.toLowerCase();
@@ -39,7 +53,7 @@ function CheckpointPanel({ checkpoint, renderApproval }) {
     });
     const { prompt } = checkpoint;
     const { stdout } = useStdout();
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: inkColor("accent"), paddingX: 1, children: [renderApproval ? (renderApproval(prompt)) : (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: prompt.title }), previewLines(prompt.lines, stdout.rows).map((line, index) => (_jsx(Text, { children: line }, index))), !decision && prompt.question ? _jsx(Text, { dimColor: true, children: prompt.question }) : null] })), decision ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: t().proceed }) })) : null, _jsx(Box, { marginTop: decision ? 0 : 1, children: _jsx(Select, { options: decision ? decisionOptions() : manualOptions(), onChange: (value) => checkpoint.answer(decision ? value : "") }, checkpoint.id) })] }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: inkColor("accent"), paddingX: 1, children: [renderApproval ? (renderApproval(prompt)) : (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: prompt.title }), previewLines(prompt.lines, stdout.rows, reservedRows, width - PANEL_FRAME_COLUMNS).map((line, index) => (_jsx(Text, { children: line }, index))), !decision && prompt.question ? _jsx(Text, { dimColor: true, children: prompt.question }) : null] })), decision ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: t().proceed }) })) : null, _jsx(Box, { marginTop: decision ? 0 : 1, children: _jsx(Select, { options: decision ? decisionOptions() : manualOptions(), onChange: (value) => checkpoint.answer(decision ? value : "") }, checkpoint.id) })] }));
 }
 function formatTokens(count) {
     return count >= 1000 ? `${(count / 1000).toFixed(1)}k` : String(count);
@@ -67,12 +81,12 @@ function Working({ label, startedAt, width }) {
     return _jsx(Text, { children: fitWidth(`${ui.working(`${glyph} ${label}`)} ${ui.dim(`(${seconds}s · ${t().escToInterrupt})`)}`, width) });
 }
 /** Line in progress, checkpoint panel or spinner, the input, and the status bar. */
-function LiveArea({ session, checkpoint, renderApproval, mode, width, statusExtra, modeSwitchable, children }) {
+function LiveArea({ session, checkpoint, renderApproval, mode, width, statusExtra, modeSwitchable, reservedRows, children }) {
     // The mode in the spinner's color; the rest dim.
     const plain = statusText(mode, session.turns, session.usage, { contextPercent: session.contextPercent, modeSwitchable }) + (statusExtra ? ` · ${statusExtra}` : "");
     const cut = mode ? plain.indexOf(" · ") : -1;
     const status = cut > 0 ? ui.working(plain.slice(0, cut)) + ui.dim(plain.slice(cut)) : ui.dim(plain);
-    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, width: width, marginTop: session.liveGap ? 1 : 0, children: [stripAnsi(session.live) ? _jsx(Text, { children: session.live }) : null, checkpoint ? (_jsx(CheckpointPanel, { checkpoint: checkpoint, renderApproval: renderApproval })) : session.busy ? (
+    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, width: width, marginTop: session.liveGap ? 1 : 0, children: [stripAnsi(session.live) ? _jsx(Text, { children: session.live }) : null, checkpoint ? (_jsx(CheckpointPanel, { checkpoint: checkpoint, renderApproval: renderApproval, reservedRows: reservedRows, width: width })) : session.busy ? (
             // Always one blank line above the spinner: from this margin, or from the live area's
             // own when a separator is pending and nothing is written above the spinner yet.
             _jsxs(Box, { flexDirection: "column", marginTop: stripAnsi(session.live) || !session.liveGap ? 1 : 0, children: [_jsx(Working, { label: session.activity ?? t().thinking, startedAt: session.turnStartedAt, width: width }), session.subagentActivity ? _jsx(Text, { dimColor: true, children: fitWidth(`  ↳ ${session.subagentActivity}`, width) }) : null] })) : null, checkpoint ? null : children, _jsx(Text, { children: fitWidth(status, width) })] }));
@@ -147,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) };
     }
@@ -209,7 +228,9 @@ function FullscreenSession({ session, checkpoint, renderApproval, mode, header,
     const statusExtra = [anchor === null ? null : t().linesBelow(below), copied]
         .filter(Boolean)
         .join(" · ");
-    return (_jsxs(Box, { flexDirection: "column", width: columns - 1, height: rows, children: [header && header.length > 0 ? (_jsx(Box, { flexDirection: "column", flexShrink: 0, marginBottom: 1, children: header.map((line, i) => (_jsx(Text, { wrap: "truncate-end", children: line || " " }, i))) })) : null, _jsx(Box, { ref: historyRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", justifyContent: "flex-end", children: wrapped.rows.slice(start, end).map((row, i) => (_jsx(Text, { wrap: "truncate-end", children: highlightRow(row, selection, start + i) || " " }, start + i))) }), _jsx(LiveArea, { session: session, checkpoint: checkpoint, renderApproval: renderApproval, mode: mode, width: width, statusExtra: statusExtra || undefined, modeSwitchable: modeSwitchable, children: children })] }));
+    return (_jsxs(Box, { flexDirection: "column", width: columns - 1, height: rows, children: [header && header.length > 0 ? (_jsx(Box, { flexDirection: "column", flexShrink: 0, marginBottom: 1, children: header.map((line, i) => (_jsx(Text, { wrap: "truncate-end", children: line || " " }, i))) })) : null, _jsx(Box, { ref: historyRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", justifyContent: "flex-end", children: wrapped.rows.slice(start, end).map((row, i) => (_jsx(Text, { wrap: "truncate-end", children: highlightRow(row, selection, start + i) || " " }, start + i))) }), _jsx(LiveArea, { session: session, checkpoint: checkpoint, renderApproval: renderApproval, mode: mode, width: width, statusExtra: statusExtra || undefined, modeSwitchable: modeSwitchable, 
+                // The pinned header (and the blank row under it) is taken from the preview too.
+                reservedRows: PANEL_RESERVED_ROWS + (header && header.length > 0 ? header.length + 1 : 0), children: children })] }));
 }
 /** History, line in progress, current action, checkpoint panel and status bar. */
 export function SessionView({ model, interaction, renderApproval, mode, closed, fullscreen, header, onCopy, modeSwitchable, children }) {

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

@@ -9,4 +9,9 @@ export declare function renderMarkdown(source: string, width: number): string[];
  * Where the finished blocks end in a reply still streaming: after its last blank line
  * outside a code fence. Everything before it renders for good; the rest is still growing.
  */
+/**
+ * Whether `source` holds a table: its columns are sized from all its rows, so none of its
+ * rows is final until the table is (see the session model's streaming).
+ */
+export declare function hasTable(source: string): boolean;
 export declare function finishedLength(source: string): number;

package/dist/tui/ink/markdown.js

@@ -173,6 +173,13 @@ function decodeEntities(text) {
  * Where the finished blocks end in a reply still streaming: after its last blank line
  * outside a code fence. Everything before it renders for good; the rest is still growing.
  */
+/**
+ * Whether `source` holds a table: its columns are sized from all its rows, so none of its
+ * rows is final until the table is (see the session model's streaming).
+ */
+export function hasTable(source) {
+    return marked.lexer(source, { gfm: true }).some((token) => token.type === "table");
+}
 export function finishedLength(source) {
     let fenceOpen = false;
     let cut = 0;

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,11 +45,27 @@ 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, and Shift+Tab switches between the modes it allows ("guided" and
-     * "interactive"; an autonomous session can't switch). With a session opener, the one it
-     * returns is used instead.
+     * current mode, Shift+Tab switches between the modes it allows ("guided", "interactive"
+     * and "plan"; an autonomous session can't switch), and entering or leaving plan mode is
+     * told to the model with the next message. With a session opener, the one it returns is
+     * used instead.
      */
     modeControl?: ModeControl;
     /**

package/dist/tui/ink/runChatInk.js

@@ -6,7 +6,7 @@ import { useSyncExternalStore } from "react";
 import { Box, render, Text, useInput } from "ink";
 import { Select } from "@inkjs/ui";
 import { getInteractionPort, setInteractionPort } from "../../core/interaction.js";
-import { createInputQueue } from "../../core/session.js";
+import { createInputQueue, togglePlanMode } from "../../core/session.js";
 import { runQuery } from "../../core/runner.js";
 import { listRuns, readConversation } from "../../core/runs.js";
 import { capHistory, loadHistory, runChatTui, saveHistory, slashCommandToken } from "../chatTui.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),
@@ -244,7 +246,7 @@ export async function runChatInk(options, tuiOptions = {}) {
     let generation = 0;
     function connect() {
         const own = ++generation;
-        queue = createInputQueue();
+        queue = createInputQueue({ modeControl: modeControl() });
         run = runQuery(queue.iterable, { ...current.options, promptSuggestions: tuiOptions.promptSuggestions ?? true });
         const events = run.events[Symbol.asyncIterator]();
         input.setMode(modeControl()?.mode ?? null);
@@ -253,7 +255,11 @@ export async function runChatInk(options, tuiOptions = {}) {
         knownCommands = run.supportedCommands().then((commands) => new Set(commands.flatMap((c) => [c.name, ...(c.aliases ?? [])])), () => null);
         void knownCommands.then((names) => {
             const exits = [...exitCommands].filter((c) => c.startsWith("/")).map((c) => c.slice(1));
-            const local = [...(tuiOptions.terminalIntegration === false ? [] : ["copy"]), ...(runsDir ? ["resume"] : [])];
+            const local = [
+                ...(tuiOptions.terminalIntegration === false ? [] : ["copy"]),
+                ...(runsDir ? ["resume"] : []),
+                ...(modeControl()?.switchable.includes("plan") ? ["plan"] : []),
+            ];
             input.setCommands([...new Set([...(names ?? []), ...exits, ...local])].sort());
         });
         void (async () => {
@@ -382,6 +388,16 @@ export async function runChatInk(options, tuiOptions = {}) {
                 await resume();
                 continue;
             }
+            // A local command too: into plan mode, or back to the mode it was entered from.
+            if (line.toLowerCase() === "/plan") {
+                const control = modeControl();
+                const next = control ? togglePlanMode(control) : null;
+                if (next)
+                    input.setMode(next);
+                else
+                    model.writeLine(ui.dim(t().modeLocked(control?.mode ?? tuiOptions.mode)));
+                continue;
+            }
             const commandToken = slashCommandToken(line);
             if (commandToken) {
                 const names = await knownCommands;

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

@@ -1,7 +1,7 @@
 import { createFriendlyToolLabel } from "../../core/toolLabels.js";
 import { createConsoleRenderer } from "../consoleRenderer.js";
 import { fitWidth, stripAnsi } from "./lineBuffer.js";
-import { finishedLength, renderMarkdown } from "./markdown.js";
+import { finishedLength, hasTable, renderMarkdown } from "./markdown.js";
 import { toolGroupExpanded, toolGroupSummary } from "./toolGroup.js";
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.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,
@@ -120,6 +121,15 @@ export function createSessionModel(options = {}) {
         if (!rest.trim())
             return [];
         const rows = renderMarkdown(rest, mdWidth());
+        // A table's columns are sized from all its rows, so a later row can widen rows already
+        // drawn: an unfinished table is never moved to the history, and only its latest rows
+        // show live until its block ends and it goes to the history whole.
+        if (hasTable(rest)) {
+            const shown = segmentShown;
+            const live = decorate(rows.slice(Math.max(rowsCommitted, rows.length - LIVE_ROWS)));
+            segmentShown = shown;
+            return live;
+        }
         const overflow = rows.length - rowsCommitted - LIVE_ROWS;
         if (overflow > 0) {
             const lead = segmentShown && rowsCommitted === 0 ? [""] : [];
@@ -137,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));
@@ -152,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.13.1",
+  "version": "0.15.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",