@falkenslab/agent-kit 0.13.0 → 0.14.0

package/README.md

@@ -1,105 +1,110 @@
-# agent-kit
-
-[![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/)
-
-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.
-- **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 switches between guided and step by step
-  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 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
+```

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?",

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?",

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?",

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 ?",

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";

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) })] }));
@@ -209,7 +223,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

@@ -1,5 +1,6 @@
 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 Theme } from "../theme.js";
@@ -31,6 +32,13 @@ export interface ProgressView extends ConsoleRenderer {
     /** Removes the live area and restores the previous interaction port; await it before printing anything else. */
     close(): Promise<void>;
 }
+/**
+ * The console renderer's methods on top of a session model, so what a caller writes lands in
+ * the view (and in `onWrite`, through the model), not only in the model's inner console
+ * renderer, whose own output goes nowhere. The view draws whole lines: `write()` text waits
+ * until its line ends (a "\n" in it, `writeLine()` or `endLine()`).
+ */
+export declare function progressRenderer(model: SessionModel): ConsoleRenderer;
 /**
  * The Ink counterpart of `createConsoleRenderer()` for one-shot ("run"-style) sessions: the
  * same methods and the same text (so `onWrite` logs exactly what the console version

package/dist/tui/ink/progressView.js

@@ -23,6 +23,43 @@ function ProgressApp({ model, interaction, renderApproval, mode, closed }) {
     }, { isActive: checkpoint !== null });
     return _jsx(SessionView, { model: model, interaction: interaction, renderApproval: renderApproval, mode: mode, closed: closed });
 }
+/**
+ * The console renderer's methods on top of a session model, so what a caller writes lands in
+ * the view (and in `onWrite`, through the model), not only in the model's inner console
+ * renderer, whose own output goes nowhere. The view draws whole lines: `write()` text waits
+ * until its line ends (a "\n" in it, `writeLine()` or `endLine()`).
+ */
+export function progressRenderer(model) {
+    let partial = "";
+    const flush = () => {
+        if (!partial)
+            return;
+        const line = partial;
+        partial = "";
+        model.writeLine(line);
+    };
+    return {
+        render: (event) => {
+            flush();
+            model.render(event);
+        },
+        write(text) {
+            const lines = (partial + text).split("\n");
+            partial = lines.pop() ?? "";
+            for (const line of lines)
+                model.writeLine(line);
+        },
+        writeLine(text) {
+            flush();
+            model.writeLine(text);
+        },
+        endLine: flush,
+        startTurn: () => model.startTurn(),
+        get atLineStart() {
+            return partial === "" && model.renderer.atLineStart;
+        },
+    };
+}
 /**
  * The Ink counterpart of `createConsoleRenderer()` for one-shot ("run"-style) sessions: the
  * same methods and the same text (so `onWrite` logs exactly what the console version
@@ -47,14 +84,7 @@ export function createProgressView(options = {}) {
     model.startTurn();
     let closing = null;
     return {
-        render: model.render,
-        write: (text) => model.renderer.write(text),
-        writeLine: (text) => model.renderer.writeLine(text),
-        endLine: () => model.renderer.endLine(),
-        startTurn: () => model.startTurn(),
-        get atLineStart() {
-            return model.renderer.atLineStart;
-        },
+        ...progressRenderer(model),
         close() {
             closing ??= (async () => {
                 setInteractionPort(previousPort);

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

@@ -47,9 +47,10 @@ export interface InkChatOptions extends ChatTuiOptions {
     toolPhrase?: (toolName: string) => ToolPhrase | undefined;
     /**
      * 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";
@@ -244,7 +244,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 +253,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 +386,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.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";
@@ -120,6 +120,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 ? [""] : [];

package/dist/tui/ink/wizard.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { stdin, stdout } from "node:process";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { Box, render, Static, Text, useApp, useInput, useStdout } from "ink";
 import wrapAnsi from "wrap-ansi";
 import { liveWidth } from "./sessionModel.js";
@@ -77,6 +77,16 @@ export function Wizard({ steps, title, onDone }) {
     const [answers, setAnswers] = useState({});
     const [done, setDone] = useState([]);
     const [index, setIndex] = useState(() => nextIndex(steps, -1, {}));
+    const [finished, setFinished] = useState(null);
+    // Exits after the render that writes the last answer's ✔ line: exiting in the same handler
+    // unmounted Ink before it wrote that <Static> item, leaving the last question unanswered on
+    // screen.
+    useEffect(() => {
+        if (!finished)
+            return;
+        onDone(finished);
+        exit();
+    }, [finished]);
     useInput((input, key) => {
         if (key.ctrl && input === "c") {
             onDone(null);
@@ -90,10 +100,8 @@ export function Wizard({ steps, title, onDone }) {
         setDone([...done, { message: resolve(step.message, answers), text: summary(step, value, answers) }]);
         const following = nextIndex(steps, index, next);
         setIndex(following);
-        if (following >= steps.length) {
-            onDone(next);
-            exit();
-        }
+        if (following >= steps.length)
+            setFinished(next);
     }
     // The title and the answered steps go to <Static>: written once, never redrawn, so a long
     // menu can't grow the live area past the terminal's height.

package/package.json

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