@knightcodeai/cli 0.20.0 → 0.21.1

package/docs/desktop.md

@@ -7,8 +7,40 @@ configuration lives in the files the terminal reads (`settings.json`, `mcp.json`
 `tools.json`); the app's Settings edit those same files, so a change made in either place
 shows in both.
 
-The app is in development and not yet published. Phase S1 (threads, transcript, composer,
-approvals) is usable from a source checkout.
+Installers come from the GitHub releases tagged `desktop-v<version>`; none is published yet,
+so for now the app runs from a source checkout.
+
+## Installing
+
+Each installer carries its own `knightcode` binary as the app server, so nothing needs to be
+on `PATH`. None is signed by a recognised publisher yet:
+
+- Windows: run `KnightCode-<version>.Setup.exe`. It installs for your user only, into
+  `%LOCALAPPDATA%\KnightCodeDesktop`, with Start menu and desktop shortcuts; remove it from
+  Settings › Apps. SmartScreen says "Windows protected your PC" the first time: choose
+  More info, then Run anyway.
+- macOS: open the `.dmg` for your Mac (`arm64` for Apple silicon, `x64` for Intel) and drag
+  KnightCode to Applications. The app is signed ad hoc, not notarized, so the first launch
+  is refused: open System Settings › Privacy & Security and choose Open Anyway, or run
+  `xattr -dr com.apple.quarantine /Applications/KnightCode.app` once.
+- Linux: install the `.deb` (`sudo apt install ./knightcode-desktop_<version>_amd64.deb`) or
+  the `.rpm` (`sudo dnf install ./knightcode-desktop-<version>-1.x86_64.rpm`).
+
+Check a download against the release's `SHA256SUMS`.
+
+## Updates
+
+- Windows: the app checks at launch and every 4 hours, and downloads a newer version in
+  the background. An Update button then shows at the right of the title bar, and Settings ›
+  About offers Restart to update; if threads are running it asks first, since quitting
+  interrupts them. Help › Check for Updates… checks now.
+- macOS: the app checks the same way and shows Update when a newer version exists, which
+  opens the release page to download it (it cannot install itself while it is signed ad
+  hoc). KnightCode › Check for Updates… checks now.
+- Linux: install the newer `.deb` or `.rpm` over the old one.
+
+Settings › About shows the app's and the app server's versions and when the app last
+checked.
 
 ## Running from source
 
@@ -25,7 +57,22 @@ quoting, so a path containing spaces (`C:\Program Files\...`) cannot be named; p
 on `PATH` and give the bare name. A packaged build ignores it and runs only its bundled binary.
 
 Server output goes to `app-server.log` in the app's logs folder (`%APPDATA%\KnightCode\logs`
-on Windows, `~/Library/Logs/KnightCode` on macOS, `~/.config/KnightCode/logs` on Linux).
+on Windows, `~/Library/Logs/KnightCode` on macOS, `~/.config/KnightCode/logs` on Linux). At
+5 MiB it moves to `app-server.log.1`, the older ones to `.2` up to `.4`, so at most five files
+are kept. Settings › About › Show logs opens the folder.
+
+To build the installers for this machine, stage the app server and make them; the
+installers land in `apps/desktop/out/make/`:
+
+```sh
+bun run apps/desktop/scripts/stage-server.ts   # builds knightcode for this platform
+cd apps/desktop && bun run make
+```
+
+The end-to-end tests launch the production build that packaging leaves in
+`apps/desktop/.vite/`, against an app server whose model is scripted
+(`packages/cli/test/fixtures/faux-app-server.ts`): run `bun run package`, then
+`bun run test:e2e`.
 
 ## What works
 
@@ -64,6 +111,32 @@ on Windows, `~/Library/Logs/KnightCode` on macOS, `~/.config/KnightCode/logs` on
     added, as `knightcode config` does. Built-in extensions are always on and not listed.
 
   Changes apply to threads that start or resume afterwards.
+- Side panel: Changes shows the thread's diff; the separators between hunks expand to
+  the unchanged lines around them. A file named in a tool row or in Changes opens in a
+  read-only tab beside it, at the line the tool read or changed. A tab opened in passing
+  is italic and the next one replaces it; double-click it to keep it. Each thread keeps
+  its own tabs, at most 12 files.
+- Open in: a file tab's Open button sends the file, at its line, to an editor, terminal
+  or IDE found on your machine, or to the system's default app or file manager. The app
+  remembers the last choice, per project and overall.
+- Terminal: Ctrl+\` opens a terminal in the thread's folder, in a region under the chat and
+  the side panel; Ctrl+J shows or hides it, and its top edge resizes it. The + menu offers
+  the shells found (PowerShell, Windows PowerShell, Command Prompt, Git Bash and WSL on
+  Windows; your login shell elsewhere), and the last one picked is the default. Terminals
+  belong to their thread: they keep running when the window reloads or another thread
+  opens, and end when you close them, archive or delete the thread, or quit. Copy needs a
+  selection (Ctrl+C, Ctrl+Shift+C or Ctrl+Insert); paste with Ctrl+V, Ctrl+Shift+V or
+  Shift+Insert (on macOS, Cmd+C and Cmd+V). Links in the output open in your browser.
+- Preview: the side panel's + (Ctrl+T) opens a page in a preview tab, http and https only
+  (`localhost:3000` is enough). A link to a local server in a message opens there too.
+  Each thread keeps its own cookies and storage, cleared when the thread is deleted; pages
+  get no permissions, and downloads ask where to save. Annotate (Ctrl+Shift+.) lets you
+  drag over part of the page to attach it to the message you are writing, with the page's
+  address.
+- MCP Apps: a tool from an [MCP server](mcp.md#mcp-apps) that has an app shows it in the
+  thread, under the turn's work. The app can call its own server's tools (asking you
+  first for one that may change things), send a follow-up message once you confirm it,
+  and open full screen in the side panel.
 - Archived threads: search, unarchive, or delete for good.
 - Command palette (Ctrl+K): actions and threads in one search.
 - Quitting while threads run asks first.
@@ -105,10 +178,16 @@ once. The protocol side is in [app-server.md](app-server.md#dialogs-and-extensio
 | Toggle the sidebar | Ctrl+B |
 | Back / forward | Alt+Left / Alt+Right |
 | Archive the thread | Ctrl+Shift+A |
+| Close the side panel's file tab | Ctrl+Shift+W |
+| Open a terminal / show or hide them | Ctrl+\` / Ctrl+J |
+| Next / previous terminal | Ctrl+PageDown / Ctrl+PageUp |
+| Open a preview / focus its address bar | Ctrl+T / Ctrl+L |
+| Annotate the preview | Ctrl+Shift+. |
 | Send | Enter |
 | New line | Shift+Enter |
 | Steer the running turn | Ctrl+Enter |
 | Stop the running turn | Escape (empty composer) |
 | Allow / deny an approval | Enter / Escape (card focused) |
 
-On macOS, Ctrl is Cmd. Settings › Keyboard shortcuts lists every binding.
+On macOS, Ctrl is Cmd, except in Ctrl+\` and Ctrl+PageDown/PageUp, which stay Control.
+Settings › Keyboard shortcuts lists every binding.

package/docs/environment-variables.md

@@ -90,6 +90,7 @@ These variables are read by KnightCode itself:
 | `KNIGHTCODE_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
 | `KNIGHTCODE_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
 | `KNIGHTCODE_BUG_ENDPOINT` | Override the origin `/bug` uploads go to; default is `https://remote.knightcode.dev` |
+| `KNIGHTCODE_CLEAR_ON_SHRINK` | Set to `1` to clear empty rows when rendered content shrinks; the `terminal.clearOnShrink` setting takes precedence. See [Settings](settings.md) |
 | `KNIGHTCODE_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
 | `KNIGHTCODE_CLIPBOARD_OSC52` | Set to `1` to also send copied text to the terminal with OSC 52 after the local clipboard write, as KnightCode does over SSH. Use it when a remote client reaches KnightCode without SSH variables, such as a multiplexer attached from another machine or a remote IDE daemon |
 | `KNIGHTCODE_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |

package/docs/extensions.md

@@ -262,6 +262,8 @@ A tool can run other tools with `ctx.executeTool(name, args, { signal, onUpdate
 
 See [`hello.ts`](../examples/extensions/hello.ts), [`todo.ts`](../examples/extensions/todo.ts), [`dynamic-tools.ts`](../examples/extensions/dynamic-tools.ts), and [`truncated-tool.ts`](../examples/extensions/truncated-tool.ts).
 
+A tool registered under a built-in name replaces the built-in tool. Re-registering a copy of `createBashToolDefinition(cwd)` or `createPowerShellToolDefinition(cwd)` with object spread, for example to change its rendering, keeps [background commands](usage.md#background-commands): the session runs them with its own background manager as long as the copy keeps the built-in `execute` and `parameters`. A copy that replaces `execute`, such as one that routes commands to a sandbox or a remote host, runs commands in the foreground only, and `task_stop` is not declared for it.
+
 ### Tool exposure
 
 `exposure` controls how the model reaches a tool. "Callable" means callable from other tools through `ctx.executeTool()` (`ctx.tools`), as the `codemode` tool's scripts do:
@@ -315,7 +317,7 @@ knightcode.unregisterMcpServer("jira");
 
 Servers registered while the extension loads connect when the session starts, together with the `mcp.json` servers; servers registered later connect right away, and `knightcode.unregisterMcpServer()` closes the connection and makes the server's tools unreachable. Registrations are not saved: register again on every load, for example based on the extension's own settings. A server in `mcp.json` with the same name takes precedence, and `/mcp` shows the override. Registering the same name again replaces the extension's earlier registration; names registered by another extension, invalid names, and invalid configs throw.
 
-The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#other-mcp-extensions)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `knightcode.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
+The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#replace-the-built-in-mcp-support)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `knightcode.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
 
 <a id="extensioncontext"></a>
 <a id="extensioncommandcontext"></a>

package/docs/keybindings.md

@@ -164,6 +164,7 @@ On native Windows, `app.suspend` has no default because Windows terminals do not
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
 | `app.tools.expand` | `ctrl+o` | Collapse or expand tool output |
+| `app.tools.background` | `ctrl+b` | Move running shell commands to the [background](usage.md#background-commands). Only while a command runs; otherwise the key reaches the editor, where `ctrl+b` moves the cursor left |
 | `app.message.copy` | `ctrl+x` | Copy the selected message in `/tree`; otherwise copy the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled, falling back to the last assistant message. On OAuth sign-in screens, copy the sign-in URL |
 | `app.message.followUp` | `alt+enter` (`ctrl+q` on Windows and WSL) | Queue follow-up message |
 | `app.message.dequeue` | `alt+up` (`alt+q` on Windows and WSL) | Restore queued messages to editor |

package/docs/mcp.md

@@ -243,13 +243,27 @@ When a connected server offers [resources](https://modelcontextprotocol.io/speci
 
 These tools reach every enabled, non-hidden server with resources. Their exposure is the widest exposure among those servers: `direct`, then `codemode` or `deferred`. Resource links in tool results identify `read_mcp_resource` and the server.
 
-Resources for MCP Apps, identified by `ui://` URIs or `text/html;profile=mcp-app`, are omitted because KnightCode does not render them. Resource icons are also omitted.
+Resources for MCP Apps, identified by `ui://` URIs or `text/html;profile=mcp-app`, are omitted from these tools: the desktop app draws them (see [MCP Apps](#mcp-apps)). Resource icons are also omitted.
 
 Reading and listing resources is retried once after a transient HTTP error (408, 429, or 5xx). Tool calls are not retried because the server may already have performed them.
 
+## MCP Apps
+
+A server can give a tool an interactive view with the MCP Apps extension (`io.modelcontextprotocol/ui`, Stable 2026-01-26): the tool names a `ui://` resource in `_meta.ui.resourceUri`, and the resource is an HTML document of type `text/html;profile=mcp-app`. The [desktop app](desktop.md) draws it in the tool's row. The terminal draws no apps, so KnightCode tells servers it supports them only in the desktop, and elsewhere servers answer with their text fallback.
+
+In the desktop:
+
+- A tool with an app is declared to the model whatever the server's exposure, and it cannot be called from codemode scripts: a call drawn as an app must be the model's own, which the session keeps. A tool you configured as `hidden` stays hidden and draws no app.
+- A tool whose `_meta.ui.visibility` leaves out `"model"` is not declared to the model, whatever its exposure and whether or not it has an app of its own. An app can still call it.
+- An app calls only tools of its own server whose visibility includes `"app"`. In Full access its calls run. In Ask and Auto-edit, a call to a tool not annotated `readOnlyHint` asks you first, naming the server and the tool. An app's calls do not go through the session's tool pipeline, so extension `tool_call` and `tool_result` handlers, permission gates included, do not see them.
+- An app can send a follow-up message to the thread after you confirm it, open http and https links in your browser, and ask to be shown full screen in the side panel. It cannot update the model's context.
+- The app runs in a sandboxed frame on its own origin, with no permissions (no camera, microphone, location or clipboard). It reaches the network only through the domains its resource declares in `_meta.ui.csp`; a declaration that is not a list of host sources is refused and the app does not load.
+
+[`examples/mcp-app/server.mjs`](../examples/mcp-app/server.mjs) is a small stdio server with a counter app: one tool that shows the app, one only the app may call, and one read-only tool.
+
 ## Permissions
 
-Every MCP call passes through KnightCode's tool pipeline. Extension `tool_call` and `tool_result` handlers, including permission gates, therefore apply to MCP tools. Calls made from codemode scripts carry the codemode call ID as `parentToolCallId`.
+Every MCP call the model makes passes through KnightCode's tool pipeline. Extension `tool_call` and `tool_result` handlers, including permission gates, therefore apply to MCP tools; an [MCP App](#mcp-apps)'s own calls are the exception. Calls made from codemode scripts carry the codemode call ID as `parentToolCallId`.
 
 `knightcode.getAllTools()` reports the annotations declared by each server: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. Permission extensions can use these hints to decide which calls require confirmation (see [Tool exposure](extensions.md#tool-exposure)). Resource tools are marked read-only.
 

package/docs/message-types.md

@@ -140,7 +140,7 @@ interface AssistantMessage {
 }
 ```
 
-`responseModel` records a concrete provider response model when it differs from the requested model. `responseId`, `providerThinkingLevel`, `thinkingLevel`, `diagnostics`, and `rawStopReason` preserve provider or runtime details.
+`responseModel` records the concrete model reported by the provider, when the provider reports one. It may equal the requested model. `responseId`, `providerThinkingLevel`, `thinkingLevel`, `diagnostics`, and `rawStopReason` preserve provider or runtime details.
 
 `"pending"` is used for a partial assistant message while it streams. The completed message in `message_end` has a terminal stop reason, and KnightCode does not persist `"pending"` assistant messages in session JSONL.
 

package/docs/packages.md

@@ -16,6 +16,8 @@ knightcode install ./local-package
 
 `knightcode list` shows configured packages. Use `knightcode remove <source>` to remove one and `knightcode update --extensions` to reconcile package installations. See [Command Line](cli.md#package-commands) for every package command and option.
 
+If a configured package fails to install at startup, for example because npm cannot reach the registry, KnightCode warns about it, skips that package's resources, and keeps running. KnightCode tries to install it again on the next start or `/reload`. `knightcode install` and `knightcode update --extensions` still report the failure and exit non-zero.
+
 Personal installs are written to `~/.knightcode/agent/settings.json`. Add `--local` or `-l` to write the package declaration to `.knightcode/settings.json`. KnightCode reads declarations from that file only after project trust is granted.
 
 Project packages are installed and loaded only after project trust is resolved. Packages can execute extension code and can include skills that instruct the model to run programs. Review third-party package source before installing it. Review project package declarations before granting project trust.

package/docs/plan-mode.md

@@ -69,6 +69,10 @@ to the highlighted choice; on an implement choice it is sent with the
 approval, and on Keep planning it is sent as feedback. Escape keeps planning. Review does not open automatically on resume. Session replacement, tree navigation, or a new run cancels an open
 picker. An action rechecks the shown revision before changing state.
 
+The desktop app opens review by itself too, asking "Implement this plan?":
+Yes, implement this plan; Implement in a new thread; or Exit planning.
+A fresh session is named after the plan's first line of prose.
+
 RPC reports a submission notification; `/plan` opens its review selection.
 JSON mode adds no extra output:
 the submission tool-call events contain the Markdown.

package/docs/settings.md

@@ -107,7 +107,7 @@ See [Compaction Reference](compaction.md) for trigger, summarization, and valida
 | `showHardwareCursor` | boolean | `false` | Use the terminal cursor instead of KnightCode's drawn cursor. KnightCode still positions it for input methods. |
 | `terminal.showImages` | boolean | `true` | Display inline images when supported. |
 | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells. |
-| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when rendered content shrinks. |
+| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when rendered content shrinks. When unset, `KNIGHTCODE_CLEAR_ON_SHRINK=1` enables it. |
 | `terminal.showTerminalProgress` | boolean | `false` | Show OSC 9;4 progress in the terminal tab. |
 | `terminal.hyperlinks` | `boolean \| "auto"` | `"auto"` | Override OSC 8 hyperlink detection. |
 | `terminal.images` | `"kitty" \| "iterm2" \| "auto" \| false` | `"auto"` | Override inline-image protocol detection. |
@@ -178,8 +178,8 @@ handed off by accident, and nothing is created through a symlink or junction.
 |---|---|---|---|
 | `transport` | `"auto" \| "sse" \| "websocket" \| "websocket-cached"` | `"auto"` | Preferred transport for AI providers that support multiple transports. |
 | `httpProxy` | string | None | Proxy URL applied as `HTTP_PROXY` and `HTTPS_PROXY` for KnightCode-managed HTTP clients. **Can only be set in agent-directory settings.** |
-| `httpIdleTimeoutMs` | number | `300000` | HTTP header and body idle timeout in milliseconds. Set to `0` to disable. |
-| `websocketConnectTimeoutMs` | number | `15000` | WebSocket connection timeout in milliseconds. Set to `0` to disable. |
+| `httpIdleTimeoutMs` | number \| `"disabled"` | `300000` | HTTP header and body idle timeout in milliseconds. Set to `0` or `"disabled"` to disable. |
+| `websocketConnectTimeoutMs` | number \| `"disabled"` | `15000` | WebSocket connection timeout in milliseconds. Set to `0` or `"disabled"` to disable. |
 | `retry.enabled` | boolean | `true` | Enable automatic agent-level retry for transient failures. |
 | `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts. |
 | `retry.baseDelayMs` | number | `2000` | Initial exponential-backoff delay in milliseconds. |

package/docs/slash-commands.md

@@ -64,8 +64,10 @@ Review a session before exporting or sharing it. Sessions can contain prompts, t
 | Command | Description |
 |---|---|
 | `/trust` | Save a project trust decision for future KnightCode processes |
+| `/mcp` | Manage MCP servers: sign in, reconnect, enable or disable, and change exposure |
 | `/reload` | Reload keybindings, extensions, skills, templates, themes, and context files |
 | `/hotkeys` | Show active keyboard shortcuts |
+| `/tasks` | List [background commands](usage.md#background-commands), show their output, and stop them |
 | `/changelog` | Show changelog entries |
 | `/quit` | Quit KnightCode |
 

package/docs/usage.md

@@ -41,6 +41,7 @@ You can send more input while KnightCode is working:
 | Adjust the current task | Type a message and press `Enter` |
 | Add work after the current task | Type a message and press `Alt+Enter` |
 | Return queued messages to the editor | Press `Alt+Up` |
+| Let a long command run on while KnightCode continues | Press `Ctrl+B` (see [Background commands](#background-commands)) |
 | Stop the current task | Press `Escape` |
 
 A message sent with `Enter` waits until the current response and its tool calls finish, then guides the next response. A follow-up sent with `Alt+Enter` waits until KnightCode finishes the current task. Aborting returns queued messages to the editor.
@@ -83,6 +84,28 @@ Prefix a command with `!` to run it and include its output in the conversation:
 
 Use `!!` when you want to run a command without sending its output to the model.
 
+## Background commands
+
+KnightCode can start a command in the background, and decides per command whether to. It does so for work that takes long or never exits, such as a dev server, a file watcher, or a long build or test run. The tool call returns at once and the command keeps running while KnightCode works, across turns. When the command exits, KnightCode is told how it ended, with the last lines of its output, and carries on from there; you see the same notice in the transcript.
+
+Press `Ctrl+B` while a command runs in the foreground to move it to the background. The same process keeps running; nothing starts again. The key works only while a command runs; otherwise `Ctrl+B` moves the cursor as usual.
+
+While commands run, a pill above the footer counts them: `1 shell`, `3 shells`. Press `Down` in an empty editor to select it and `Enter` to open the **Background tasks** list, or click it; `Esc` or `Up` returns to the editor. `/tasks` opens the same list. With a single command it opens on that command's details.
+
+| Key | In the list | In a command's details |
+|-----|-------------|------------------------|
+| `Up`/`Down` | Choose a command | |
+| `Enter` | Show its details | Close |
+| `x` | Stop the chosen command | Stop it |
+| `Left` | Close | Back to the list |
+| `Esc` | Close | Close |
+
+A command's details show its status and exit code, runtime, command, and the last 10 lines of its output as it arrives. Its output is also written to a file, and KnightCode reads that file when it needs the output sooner. If writing that file fails, for example on a full disk, the file is incomplete and KnightCode is told so. KnightCode stops a command with the `task_stop` tool, which is on whenever `bash` or `powershell` is.
+
+A background command ends when it exits, when KnightCode or you stop it, or when the session ends: quitting, `/new`, `/resume`, and `/fork` stop it, while `/reload` keeps it. Resuming or forking a session does not start its commands again; with your next message KnightCode is told that they were stopped. A `timeout` given with the command still stops it in the background. A command that writes more than 1 GiB of output is stopped, and at most 32 run at once.
+
+A background command has no input: one that asks a question reads end-of-file. If you press `Escape` to stop the current task, a command that ends afterwards is recorded in the conversation without starting KnightCode again; the next message you send re-arms that. In print and JSON modes KnightCode does not exit while a command it started in the background is running, so it can act on how the command ended.
+
 ## Web Tools
 
 Two tools give the agent read access to the web. Both ship disabled; turn them on with `/tools`.

package/examples/extensions/custom-provider-anthropic/index.ts

@@ -42,7 +42,7 @@ import {
 	type TextContent,
 	type ThinkingContent,
 	type Tool,
-	type ToolCall,
+	ToolCallArgumentsStream,
 	type ToolResultMessage,
 	type TranscriptContext,
 } from "@knightcode/ai";
@@ -454,8 +454,9 @@ function streamCustomAnthropic(
 			const anthropicStream = client.messages.stream({ ...params }, { signal: options?.signal });
 			stream.push({ type: "start", partial: output });
 
-			type Block = (ThinkingContent | TextContent | (ToolCall & { partialJson: string })) & { index: number };
-			const blocks = output.content as Block[];
+			// Stream state per Anthropic block index, kept off the content blocks so it never reaches partial messages.
+			// ToolCallArgumentsStream reads each argument delta once and shows the arguments parsed so far.
+			const openBlocks = new Map<number, { contentIndex: number; arguments?: ToolCallArgumentsStream }>();
 
 			for await (const event of anthropicStream) {
 				if (event.type === "message_start") {
@@ -468,15 +469,12 @@ function streamCustomAnthropic(
 					calculateCost(model, output.usage);
 				} else if (event.type === "content_block_start") {
 					if (event.content_block.type === "text") {
-						output.content.push({ type: "text", text: "", index: event.index } as any);
+						output.content.push({ type: "text", text: "" });
+						openBlocks.set(event.index, { contentIndex: output.content.length - 1 });
 						stream.push({ type: "text_start", contentIndex: output.content.length - 1, partial: output });
 					} else if (event.content_block.type === "thinking") {
-						output.content.push({
-							type: "thinking",
-							thinking: "",
-							thinkingSignature: "",
-							index: event.index,
-						} as any);
+						output.content.push({ type: "thinking", thinking: "", thinkingSignature: "" });
+						openBlocks.set(event.index, { contentIndex: output.content.length - 1 });
 						stream.push({ type: "thinking_start", contentIndex: output.content.length - 1, partial: output });
 					} else if (event.content_block.type === "tool_use") {
 						output.content.push({
@@ -484,15 +482,18 @@ function streamCustomAnthropic(
 							id: event.content_block.id,
 							name: isOAuth ? fromClaudeCodeName(event.content_block.name, tools) : event.content_block.name,
 							arguments: {},
-							partialJson: "",
-							index: event.index,
-						} as any);
+						});
+						openBlocks.set(event.index, {
+							contentIndex: output.content.length - 1,
+							arguments: new ToolCallArgumentsStream(),
+						});
 						stream.push({ type: "toolcall_start", contentIndex: output.content.length - 1, partial: output });
 					}
 				} else if (event.type === "content_block_delta") {
-					const index = blocks.findIndex((b) => b.index === event.index);
-					const block = blocks[index];
-					if (!block) continue;
+					const open = openBlocks.get(event.index);
+					if (!open) continue;
+					const index = open.contentIndex;
+					const block = output.content[index]!;
 
 					if (event.delta.type === "text_delta" && block.type === "text") {
 						block.text += event.delta.text;
@@ -505,11 +506,8 @@ function streamCustomAnthropic(
 							delta: event.delta.thinking,
 							partial: output,
 						});
-					} else if (event.delta.type === "input_json_delta" && block.type === "toolCall") {
-						(block as any).partialJson += event.delta.partial_json;
-						try {
-							block.arguments = JSON.parse((block as any).partialJson);
-						} catch {}
+					} else if (event.delta.type === "input_json_delta" && block.type === "toolCall" && open.arguments) {
+						block.arguments = open.arguments.append(event.delta.partial_json);
 						stream.push({
 							type: "toolcall_delta",
 							contentIndex: index,
@@ -520,20 +518,19 @@ function streamCustomAnthropic(
 						block.thinkingSignature = (block.thinkingSignature || "") + (event.delta as any).signature;
 					}
 				} else if (event.type === "content_block_stop") {
-					const index = blocks.findIndex((b) => b.index === event.index);
-					const block = blocks[index];
-					if (!block) continue;
+					const open = openBlocks.get(event.index);
+					if (!open) continue;
+					openBlocks.delete(event.index);
+					const index = open.contentIndex;
+					const block = output.content[index]!;
 
-					delete (block as any).index;
 					if (block.type === "text") {
 						stream.push({ type: "text_end", contentIndex: index, content: block.text, partial: output });
 					} else if (block.type === "thinking") {
 						stream.push({ type: "thinking_end", contentIndex: index, content: block.thinking, partial: output });
-					} else if (block.type === "toolCall") {
-						try {
-							block.arguments = JSON.parse((block as any).partialJson);
-						} catch {}
-						delete (block as any).partialJson;
+					} else if (block.type === "toolCall" && open.arguments) {
+						// One full parse of the complete text; malformed arguments are reported in `argumentsError`.
+						Object.assign(block, open.arguments.finish());
 						stream.push({ type: "toolcall_end", contentIndex: index, toolCall: block, partial: output });
 					}
 				} else if (event.type === "message_delta") {
@@ -563,7 +560,6 @@ function streamCustomAnthropic(
 			stream.push({ type: "done", reason: output.stopReason, message: output });
 			stream.end();
 		} catch (error) {
-			for (const block of output.content) delete (block as any).index;
 			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
 			output.errorMessage = error instanceof Error ? error.message : JSON.stringify(error);
 			stream.push({ type: "error", reason: output.stopReason, error: output });

package/examples/extensions/todo.ts

@@ -273,6 +273,9 @@ export default function (knightcode: ExtensionAPI) {
 
 				case "clear":
 					return new Text(theme.fg("success", "✓ ") + theme.fg("muted", "Cleared all todos"), 0, 0);
+
+				default:
+					return new Text(result.content[0]?.type === "text" ? theme.fg("error", result.content[0].text) : "", 0, 0);
 			}
 		},
 	});

package/examples/mcp-app/server.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * A stdio MCP server with one MCP App: a counter. It needs no dependencies (newline-delimited JSON-RPC over stdio).
+ *
+ * - `show_counter` (model and app): shows the counter; its `_meta.ui.resourceUri` names the app, `ui://counter/app.html`.
+ * - `increment` (app only, `_meta.ui.visibility: ["app"]`): changes the count, so outside Full access the desktop
+ *   asks the user before it runs.
+ * - `read_count` (read-only): what the count is; an app may call it without asking.
+ *
+ * Add it to `~/.knightcode/agent/mcp.json`:
+ *
+ *   { "mcpServers": { "counter": { "command": "node", "args": ["/path/to/server.mjs"], "exposure": "direct" } } }
+ *
+ * In the desktop app, ask KnightCode to show the counter: the tool's row draws the app. In the terminal, which draws
+ * no apps, the tool answers with its text.
+ */
+
+import { createInterface } from "node:readline";
+
+const APP_URI = "ui://counter/app.html";
+const APP_MIME = "text/html;profile=mcp-app";
+let count = 0;
+
+const APP_HTML = `<!doctype html>
+<meta charset="utf-8">
+<style>
+	body { margin: 0; padding: 12px 14px; font: 14px var(--font-sans, system-ui); color: var(--color-text-primary, #111);
+		background: var(--color-background-primary, transparent); }
+	.row { display: flex; align-items: center; gap: 10px; }
+	output { font: 600 22px var(--font-mono, monospace); min-width: 3ch; }
+	button { font: inherit; padding: 4px 12px; border-radius: var(--border-radius-md, 8px);
+		border: 1px solid var(--color-border-primary, #ccc); background: var(--color-background-secondary, #f4f4f4);
+		color: inherit; cursor: pointer; }
+	#status { margin-top: 8px; color: var(--color-text-secondary, #666); font-size: 12px; }
+</style>
+<div class="row">
+	<span>Count</span><output id="count">…</output>
+	<button id="add">Add one</button>
+	<button id="tell">Tell KnightCode</button>
+</div>
+<div id="status"></div>
+<script>
+	const pending = new Map();
+	let next = 0;
+	const request = (method, params) =>
+		new Promise((resolve, reject) => {
+			const id = ++next;
+			pending.set(id, { resolve, reject });
+			parent.postMessage({ jsonrpc: "2.0", id, method, params }, "*");
+		});
+	const notify = (method, params) => parent.postMessage({ jsonrpc: "2.0", method, params }, "*");
+	const show = (n) => (document.getElementById("count").textContent = String(n));
+	const status = (text) => (document.getElementById("status").textContent = text);
+	const theme = (context) => {
+		for (const [name, value] of Object.entries(context?.styles?.variables ?? {}))
+			if (value) document.documentElement.style.setProperty(name, value);
+	};
+	window.addEventListener("message", (event) => {
+		const message = event.data;
+		if (!message || message.jsonrpc !== "2.0") return;
+		if (message.id !== undefined && !message.method) {
+			const waiter = pending.get(message.id);
+			pending.delete(message.id);
+			if (message.error) waiter?.reject(new Error(message.error.message));
+			else waiter?.resolve(message.result);
+			return;
+		}
+		if (message.method === "ui/notifications/tool-result") show(message.params?.structuredContent?.count ?? "?");
+		else if (message.method === "ui/notifications/tool-cancelled") status("The call was cancelled");
+		else if (message.method === "ui/notifications/host-context-changed") theme(message.params);
+		else if (message.method === "ui/resource-teardown") parent.postMessage({ jsonrpc: "2.0", id: message.id, result: {} }, "*");
+		else if (message.method === "ping") parent.postMessage({ jsonrpc: "2.0", id: message.id, result: {} }, "*");
+	});
+	document.getElementById("add").onclick = async () => {
+		try {
+			const result = await request("tools/call", { name: "increment", arguments: { by: 1 } });
+			show(result.structuredContent.count);
+			status("");
+		} catch (error) {
+			status(error.message);
+		}
+	};
+	document.getElementById("tell").onclick = async () => {
+		const now = document.getElementById("count").textContent;
+		try {
+			await request("ui/message", { role: "user", content: [{ type: "text", text: "The counter app shows " + now + "." }] });
+			status("Sent");
+		} catch (error) {
+			status(error.message);
+		}
+	};
+	(async () => {
+		const init = await request("ui/initialize", {
+			protocolVersion: "2026-01-26",
+			appInfo: { name: "counter", version: "1.0.0" },
+			appCapabilities: { availableDisplayModes: ["inline"] },
+		});
+		theme(init.hostContext);
+		notify("ui/notifications/initialized", {});
+		notify("ui/notifications/size-changed", { height: document.documentElement.scrollHeight });
+	})();
+</script>`;
+
+const tools = [
+	{
+		name: "show_counter",
+		description: "Show the counter app with the current count.",
+		inputSchema: { type: "object", properties: {} },
+		annotations: { readOnlyHint: true },
+		_meta: { ui: { resourceUri: APP_URI } },
+	},
+	{
+		name: "increment",
+		description: "Add to the counter.",
+		inputSchema: { type: "object", properties: { by: { type: "number" } } },
+		_meta: { ui: { visibility: ["app"] } },
+	},
+	{
+		name: "read_count",
+		description: "Read the counter.",
+		inputSchema: { type: "object", properties: {} },
+		annotations: { readOnlyHint: true },
+	},
+];
+
+const countResult = (text) => ({ content: [{ type: "text", text }], structuredContent: { count } });
+
+function answer(method, params) {
+	switch (method) {
+		case "initialize":
+			return {
+				protocolVersion: params?.protocolVersion ?? "2025-11-25",
+				capabilities: { tools: {}, resources: {} },
+				serverInfo: { name: "counter-app", version: "1.0.0" },
+			};
+		case "ping":
+			return {};
+		case "tools/list":
+			return { tools };
+		case "tools/call":
+			if (params?.name === "show_counter") return countResult(`The counter is at ${count}.`);
+			if (params?.name === "increment") {
+				count += Number(params.arguments?.by ?? 1);
+				return countResult(`The counter is now ${count}.`);
+			}
+			if (params?.name === "read_count") return countResult(String(count));
+			throw Object.assign(new Error(`no tool ${params?.name}`), { code: -32602 });
+		case "resources/list":
+			return { resources: [{ uri: APP_URI, name: "Counter app", mimeType: APP_MIME }] };
+		case "resources/read":
+			if (params?.uri !== APP_URI) throw Object.assign(new Error(`no resource ${params?.uri}`), { code: -32002 });
+			return {
+				contents: [
+					{ uri: APP_URI, mimeType: APP_MIME, text: APP_HTML, _meta: { ui: { prefersBorder: true, csp: {} } } },
+				],
+			};
+		default:
+			throw Object.assign(new Error(`method not found: ${method}`), { code: -32601 });
+	}
+}
+
+const write = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
+createInterface({ input: process.stdin }).on("line", (line) => {
+	let message;
+	try {
+		message = JSON.parse(line);
+	} catch {
+		return;
+	}
+	// Notifications (no id) need no answer.
+	if (message.id === undefined || message.id === null) return;
+	try {
+		write({ jsonrpc: "2.0", id: message.id, result: answer(message.method, message.params) });
+	} catch (error) {
+		write({ jsonrpc: "2.0", id: message.id, error: { code: error.code ?? -32603, message: error.message } });
+	}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "description": "KnightCode — a local, BYOK terminal coding agent powered by OpenRouter.",
   "type": "module",
   "repository": {