@knightcodeai/cli-linux-x64 0.7.0 → 0.9.0

package/bin/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @knightcodeai/cli
 
+## 0.9.0
+
+### Added
+
+- Added unsubscribe to extension events: `knightcode.on(event, handler)` now returns a function that removes that one registration, so an extension can listen once or stop listening without reloading. Removing a handler never affects a dispatch already in progress.
+
+- Added what the desktop IDE's first run needs to `knightcode-engine`:
+
+  - `PUT /v1/models/default` records the model you pick in the IDE as your default, the same setting `/model` writes in the CLI, so both use one choice.
+  - `GET` and `PUT /v1/settings/telemetry` read and change the install-telemetry setting the CLI already has, so the IDE asks once and both follow the answer. The switch refuses to move while `KNIGHTCODE_TELEMETRY` is set in the environment.
+  - When the IDE starts the engine, it sends the same anonymous install ping as the CLI, once per IDE version, and not at all if you turned install telemetry off.
+
+- Added `/undo`: pick an earlier user message and go back to it, with the option to restore every file the abandoned turns edited. Files are backed up before each `edit` and `write`, so the restore needs no git; `/tree` and double-Escape offer the same restore. `KNIGHTCODE_DISABLE_FILE_CHECKPOINTS=1` turns the backups off.
+
+- Added click-to-expand for compaction, branch-summary and skill entries in the transcript. A left click toggles them the same way the expand shortcut does.
+
+- Added a `terminal` option to `InteractiveMode`, so an embedder or test can drive the interactive UI against its own terminal implementation instead of the process's.
+
+### Changed
+
+- Changed long shell command timings to read as minutes and hours (`26m 32s`, `2h 3m 4s`) instead of a raw seconds count; anything under a minute still shows tenths of a second.
+
+- Changed the copy shortcut's description in the hotkeys list and keybinding settings to say what it does: it copies the current selection, or the last assistant message when nothing is selected.
+
+- Changed the transcript types so tool-call arguments and tool-result `details` are declared as JSON values instead of `any`. A tool that puts a `Date`, a function or `undefined` into `details` is now a type error rather than something that silently fails to round-trip through the session file.
+
+- Changed the Kimi For Coding catalog to read from the provider's current listing, which reports the 1M-token context window and low / high / max thinking levels for `kimi-for-coding`.
+
+### Fixed
+
+- Fixed thinking blocks being dropped on the next turn when an Anthropic-compatible endpoint reports a different model name than the one requested. The requested model stays on the message, and the reported one is kept separately for cost attribution.
+
+- Fixed the "Anthropic dropped thinking" notice repeating on every turn and flooding the transcript with per-block reasons. It now shows a short count, only when a response drops more blocks than the previous one, and not again when a session is reloaded; the details stay in the session file.
+
+- Fixed a shell command killed by a signal (an OOM kill, `kill -9`, a `SIGTERM`) being reported to the model as a success. It now fails with the conventional exit code (137 for `SIGKILL`, 143 for `SIGTERM`) and keeps the output it produced before dying.
+
+- Fixed a bare `400` or `413` with no body from any provider being treated as a context overflow and triggering compaction. Only Cerebras reports overflow that way, so the rule now applies to Cerebras alone.
+
+- Fixed automatic compaction doing nothing when the newest tool result alone exceeds the retained-token budget. The cut now falls back to the assistant message that made the tool call, so older history is summarized before the next request instead of the session overflowing.
+
+- Fixed DeepSeek V4.1 Flash offering the wrong thinking levels on OpenRouter and OpenCode Go. Both now expose the low / high / max efforts the model actually accepts, and OpenCode Go lists it under its current ID, `deepseek-v4.1-flash`.
+
+- Fixed `knightcode-engine` answering a login request whose body is not JSON, or is too large, with a 500 instead of a 400 or 413.
+
+- Fixed a `before_agent_start` handler that returns `systemPrompt` (or sets `forceSystemPrompt`) not actually replacing the prompt on models that accept mid-conversation system messages: they kept the original prompt at the head and received the forced text as a later update. The forced prompt is now sent as the leading system prompt for the run, and the session transcript keeps recording the structured sections instead of the forced text.
+
+- Fixed fuzzy search in the model, session and file pickers lagging on long lists; matching now skips ahead with a native substring search and returns the same results in the same order.
+
+- Fixed Gemini requests asking for thinking levels a model does not support. Turning thinking off, or picking a level the model lacks, now falls back to the lowest level that model advertises instead of a hard-coded Gemini 3 Pro / Flash guess.
+
+- Fixed llama.cpp models whose chat template supports thinking (Qwen-style `enable_thinking`) always running as non-reasoning models. Loaded models are now checked through the server's `/props`, and those templates get an on/off thinking toggle.
+
+- Fixed two transient provider failures ending the turn instead of retrying: Cloudflare `520` responses and Azure's "currently experiencing high demand" peak-load rejections are now retried like other overload errors.
+
+- Fixed Vercel AI Gateway conversations losing their thinking on the next turn. The gateway returns thinking without a signature for models it translates, and those blocks are now replayed instead of being stripped.
+
+## 0.8.0
+
+### Added
+
+- Added `allowedFallbackModels` to Anthropic model overrides in `models.json`, so you can choose which models the server may fall back to — or set an empty array to turn server-side fallback off.
+
+- Added webfetch and websearch tools — a page as pageable, greppable markdown, and results from DuckDuckGo or Brave Search — off until enabled with the new `/tools` command, which turns each built-in tool off, on for the session, or on by default, and for websearch also picks the provider and stores the Brave API key.
+
+### Changed
+
+- Changed the system prompt and tool set to live in the transcript instead of being rewritten behind it. A session records when its instructions changed or tools became available, resuming or moving between branches restores that state, and providers that support it keep their cached prompt prefix across the change. Extensions can replace individual prompt sections through `systemPromptOptions.sections`, and the deferred-tool loading path is replaced by mid-conversation tool additions on the models that accept them.
+
+- Changed a failed copy to say why: instead of a bare "Copy failed" flash, the message now names the missing clipboard backend — `wl-clipboard`, `xclip`/`xsel` or the Termux API package — and stays on screen for five seconds.
+
+### Fixed
+
+- Fixed a `user_bash` handler that throws or returns a malformed result silently falling back to the local shell — the command is now reported as failed instead of running somewhere the extension meant to prevent. A handler must return `undefined`, exactly one of `{ operations }` or `{ result }`, and nothing else.
+
+- Fixed Baseten requests to carry session-affinity headers so a conversation keeps hitting the same replica and benefits from automatic prompt caching.
+
+- Fixed Bedrock cost reporting to bill one-hour cache writes at their higher rate instead of charging every cache write at the five-minute rate.
+
+- Fixed a local copy reporting success when no clipboard backend actually took the text: the terminal-escape fallback now only counts in a remote session, where it is the terminal that owns the clipboard.
+
+- Fixed the package's public types so extension authors can import the event and result types their hooks receive, such as `ModelSelectEvent`, `ThinkingLevelSelectEvent` and the `*Result` types, instead of redeclaring them.
+
+- Fixed the thinking levels offered for Gemini models: they now follow the reasoning efforts each model actually advertises instead of a version-number guess, so newer Flash and Pro models expose their real low/medium/high range.
+
+- Fixed resuming a session by its exact ID reading every transcript in the session directory first, which made startup slow in directories with long histories.
+
 ## 0.7.0
 
 ### Added

package/bin/docs/compaction.md

@@ -151,7 +151,7 @@ See [`prepareCompaction()`](https://github.com/KnightCodeAI/knightcode/blob/main
 
 ### When It Triggers
 
-When you use `/tree` to navigate to a different branch, KnightCode offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
+When you use `/tree` to navigate to a different branch, KnightCode offers to summarize the work you're leaving. `/undo` never summarizes; it only rewinds. This injects context from the left branch into the new branch.
 
 ### How It Works
 

package/bin/docs/custom-provider.md

@@ -406,25 +406,31 @@ For providers with non-standard APIs, implement `streamSimple`. Study the existi
 
 ### Stream Pattern
 
-All providers follow the same pattern:
+All providers follow the same pattern. The context is a normalized transcript: the system prompt and tool declarations live in its system messages, so read them with `getCurrentSystemPrompt(context.messages)` and `getCurrentTools(context.messages)` rather than expecting `context.systemPrompt` or `context.tools`. Models that accept system messages mid-conversation can send them in place; otherwise call `collapseSystemMessages(context)` first to fold later system messages into the leading one.
 
 ```typescript
 import {
   type AssistantMessage,
   type AssistantMessageEventStream,
-  type Context,
   type Model,
   type SimpleStreamOptions,
+  type TranscriptContext,
   calculateCost,
+  collapseSystemMessages,
   createAssistantMessageEventStream,
+  getCurrentSystemPrompt,
+  getCurrentTools,
 } from "@knightcode/ai";
 
 function streamMyProvider(
   model: Model<any>,
-  context: Context,
+  context: TranscriptContext,
   options?: SimpleStreamOptions
 ): AssistantMessageEventStream {
   const stream = createAssistantMessageEventStream();
+  const transcript = collapseSystemMessages(context);
+  const systemPrompt = getCurrentSystemPrompt(transcript.messages);
+  const tools = getCurrentTools(transcript.messages);
 
   (async () => {
     // Initialize output message
@@ -668,10 +674,10 @@ interface ProviderConfig {
   /** API type for streaming. Required at provider or model level when defining models. */
   api?: Api;
 
-  /** Custom streaming implementation for non-standard APIs. */
+  /** Custom streaming implementation for non-standard APIs. Receives a normalized transcript. */
   streamSimple?: (
     model: Model<Api>,
-    context: Context,
+    context: TranscriptContext,
     options?: SimpleStreamOptions
   ) => AssistantMessageEventStream;
 

package/bin/docs/environment-variables.md

@@ -84,6 +84,7 @@ These variables are read by KnightCode itself:
 | `KNIGHTCODE_SERVER_DIR` | Override the experimental server profile and socket directory; default is `~/.knightcode/server` |
 | `KNIGHTCODE_SERVER_ID` | Select the logical experimental server ID when `--server-id` is omitted |
 | `KNIGHTCODE_OFFLINE` | Disable startup network operations, including update checks, package updates, and install/update telemetry |
+| `KNIGHTCODE_DISABLE_FILE_CHECKPOINTS` | Set to `1`, `true`, or `yes` to stop backing up files before edits; `/undo` then rewinds the conversation only. See [Sessions](sessions.md#file-restore) |
 | `KNIGHTCODE_SKIP_VERSION_CHECK` | Disable the `knightcode.dev` latest-version request |
 | `KNIGHTCODE_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
 | `KNIGHTCODE_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
@@ -93,6 +94,7 @@ These variables are read by KnightCode itself:
 | `KNIGHTCODE_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |
 | `KNIGHTCODE_TRUE_COLOR` | Override truecolor detection with `1`, `0`, or `auto` |
 | `KNIGHTCODE_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase if Alt-key input is misread as Escape |
+| `BRAVE_API_KEY` | Brave Search key for `websearch` when none is stored with `/tools`; see [Web tools](usage.md#web-tools) |
 | `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
 | `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
 

package/bin/docs/extensions.md

@@ -333,7 +333,7 @@ user sends another prompt ◄─────────────────
   ├─► session_compact (success)
   └─► session_compact_failed (failure or abort)
 
-/tree navigation
+/tree, /undo, or double-Escape navigation
   ├─► session_before_tree (can cancel or customize)
   └─► session_tree
 
@@ -492,7 +492,7 @@ knightcode.on("session_compact_failed", async (event, ctx) => {
 
 #### session_before_tree / session_tree
 
-Fired on `/tree` navigation. See [Sessions](sessions.md) for tree navigation concepts.
+Fired on `/tree`, `/undo`, and double-Escape navigation. See [Sessions](sessions.md) for tree navigation concepts.
 
 ```typescript
 knightcode.on("session_before_tree", async (event, ctx) => {
@@ -538,10 +538,13 @@ knightcode.on("before_agent_start", async (event, ctx) => {
   // event.systemPrompt - current chained system prompt for this handler
   //   (includes changes from earlier before_agent_start handlers)
   // event.systemPromptOptions - structured options used to build the system prompt
-  //   .customPrompt - any custom system prompt (from --system-prompt, SYSTEM.md, or custom templates)
+  //   .customPrompt - exact prompt prefix from --system-prompt, SYSTEM.md, or custom templates
+  //   .forceSystemPrompt - optional exact replacement for the complete prompt
   //   .selectedTools - tools currently active in the prompt
   //   .toolSnippets - one-line descriptions for each tool
-  //   .promptGuidelines - custom guideline bullets
+  //   .toolGuidelines - guideline bullets keyed by tool name
+  //   .promptGuidelines - additional custom guideline bullets
+  //   .sections - custom XML-wrapped sections keyed by tag name
   //   .appendSystemPrompt - text from --append-system-prompt flags
   //   .cwd - working directory
   //   .contextFiles - AGENTS.md files and other loaded context files
@@ -560,7 +563,7 @@ knightcode.on("before_agent_start", async (event, ctx) => {
 });
 ```
 
-The `systemPromptOptions` field gives extensions access to the same structured data KnightCode uses to build the system prompt. This lets you inspect what KnightCode has loaded — custom prompts, guidelines, tool snippets, context files, skills — without re-discovering resources or re-parsing flags. Use it when your extension needs to make deep, informed changes to the system prompt while respecting user-provided configuration.
+The `systemPromptOptions` field gives extensions access to the same structured data KnightCode uses to build the system prompt. Collections are mutable. Prefer changing `sections`, `selectedTools`, or `promptGuidelines`: KnightCode diffs the resulting prompt sections against what the model already has and appends one system message patching only the changed sections. Returning `systemPrompt`, or setting `forceSystemPrompt`, replaces the whole prompt for the run: every provider receives the forced text as its leading system prompt (a cache miss when it changes), and the session transcript keeps recording the structured sections. Tool selection changes update both the prompt contributions and executable provider tools; calling `knightcode.setActiveTools()` inside the handler has the same effect as editing `selectedTools`. Models that accept system messages mid-conversation receive the patch in place and keep their cached prefix; other models get the replayed prompt as their system prompt, which is a cache miss once per change.
 
 Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` both reflect the chained system prompt as of the current handler. Later `before_agent_start` handlers can still modify it again.
 
@@ -906,6 +909,8 @@ knightcode.on("user_bash", (event, ctx) => {
 });
 ```
 
+Returning `undefined` continues to the next handler, then local execution if none handles the event. A valid result stops propagation: `operations` executes the command through the supplied backend, while `result` records the completed command without executing it.
+
 ### Input Events
 
 #### input
@@ -1125,7 +1130,7 @@ const options = ctx.getSystemPromptOptions();
 const contextPaths = options.contextFiles?.map((file) => file.path) ?? [];
 ```
 
-This has the same shape and mutability as `before_agent_start` `event.systemPromptOptions`: custom prompt, active tools, tool snippets, prompt guidelines, appended system prompt text, cwd, loaded context files, and loaded skills. It may include full context file contents, so treat it as sensitive extension-local data and avoid exposing it through command lists, logs, or autocomplete metadata.
+This has the same shape and mutability as `before_agent_start` `event.systemPromptOptions`: custom or forced prompt, active tools, tool snippets, per-tool and custom rules, custom sections, appended prompt text, cwd, loaded context files, and loaded skills. It may include full context file contents, so treat it as sensitive extension-local data and avoid exposing it through command lists, logs, or autocomplete metadata.
 
 This reports the current base prompt inputs. It does not include per-turn `before_agent_start` chained system-prompt changes, later `context` event message mutations, or `before_provider_request` payload rewrites.
 
@@ -1366,7 +1371,16 @@ export default function (knightcode: ExtensionAPI) {
 
 ### knightcode.on(event, handler)
 
-Subscribe to events. See [Events](#events) for event types and return values.
+Subscribe to events. Returns an unsubscribe function that removes only that registration. See [Events](#events) for event types and return values.
+
+```typescript
+const unsubscribe = knightcode.on("agent_end", async (event) => {
+  unsubscribe();
+  await updateIntegration(event.messages);
+});
+```
+
+Handlers run in extension load order, then registration order within each extension. Adding or removing a handler does not affect a dispatch already in progress.
 
 ### knightcode.registerTool(definition)
 
@@ -2370,42 +2384,13 @@ If a slot renderer is not defined or throws:
 
 ### Dynamic Tool Loading
 
-Extensions can register many tools while keeping only a small initial set active. A tool can then add more tools with `knightcode.setActiveTools()` during execution. KnightCode detects purely additive changes, records the newly available tool names on that tool result, and applies the updated active set before the next model request.
-
-This works with every model. Models with native deferred-loading support preserve the stable prompt prefix and load the new definitions at the tool-result position. Other models use the fallback described below.
+Extensions can register many tools while keeping only a small initial set active. A tool can then change the active set with `knightcode.setActiveTools()` during execution. KnightCode stores the initial prompt and tool loadout in the transcript's first system message, then appends tool and prompt deltas before the next model request. Providers that cannot represent a transition receive a complete transcript checkpoint, which may invalidate the cached prefix.
 
 The lifecycle is:
 
 1. Register every tool with `knightcode.registerTool()` so it appears in `knightcode.getAllTools()`.
 2. Keep loader tools, such as `search_tools`, active and leave searchable tools inactive.
-3. During loader execution, call `knightcode.setActiveTools([...currentTools, ...matchingTools])`. The change must be additive: do not remove currently active tools in the same call.
-4. KnightCode records which tools were added on the loader's tool result.
-5. Before the next model response, KnightCode exposes the added definitions using native deferred loading when supported, or the normal active tool list otherwise.
-
-You do not need to return provider-specific tool references or mark the loader as a special search tool. The active-tool change is the signal. Names passed to `knightcode.setActiveTools()` must already be registered; unknown names are ignored.
-
-#### Models with native deferred loading
-
-- **Anthropic**
-  - **Models:** Sonnet, Opus, Fable version 4.5 or newer (without Haiku)
-  - **Native representation:** Deferred definitions use `defer_loading`; the load point uses `tool_reference` content.
-- **Fireworks Messages API**
-  - **Native representation:** Deferred definitions use `defer_loading`; the load point uses `tool_reference` content.
-  - **Loader names:** Use `ToolSearch` or `tool_search` for prefix deferral. Other loader names still work, but Fireworks includes the loaded schemas in the initial tool prefix, losing the cache benefit.
-  - This does not change API routing: Fireworks GLM models and Kimi K3 use Chat Completions, not Messages.
-- **OpenAI**
-  - **Models:** `gpt-5.4` and newer family
-  - **Native representation:** KnightCode adds completed client `tool_search_call` and `tool_search_output` items at the load point.
-
-For a verified custom model or proxy, native handling can be enabled with `compat.supportsToolReferences: true` for `anthropic-messages`, or `compat.supportsToolSearch: true` for `openai-responses` and `openai-codex-responses`. Leave these disabled unless the endpoint and model accept the corresponding native protocol.
-
-#### Fallback behavior
-
-For all other models and providers, dynamic activation still works: KnightCode sends the complete current active tool list normally on the next request. The model can call the newly activated tools, but adding their definitions may invalidate the provider's cached prompt prefix.
-
-KnightCode also uses this safe fallback when the active set is not purely additive, such as replacing one group of tools with another. Tool removals therefore work, but they do not use deferred loading.
-
-For the best cache behavior, keep the loader tool active for the whole session and add tools instead of replacing the active set. Also note that activating a tool with `promptSnippet` or `promptGuidelines` rebuilds the system prompt; that system-prompt change can invalidate the prefix even when the provider supports deferred schemas. Lazily loaded tools should usually rely on their tool `description` and omit active-only prompt metadata.
+3. During loader execution, call `knightcode.setActiveTools()` with the desired active tool names. Names must already be registered; unknown names are ignored.
 
 #### Search tool example
 
@@ -2507,7 +2492,7 @@ export default function (knightcode: ExtensionAPI) {
 }
 ```
 
-When `search_tools` adds a match, the model receives that definition on the immediately following request. On a native-capable model the definition is anchored after the search result without changing the initial tool-schema prefix. On other models it appears in the normal tool list on that same following request.
+When `search_tools` adds a match, the model receives the complete updated tool list on the immediately following request.
 
 ## Custom UI
 

package/bin/docs/models.md

@@ -436,6 +436,7 @@ Built-in Anthropic models enable `supportsStrictTools` in their model metadata.
 | `supportsMidConvoEffort` | Whether the exact Claude model transport supports per-turn effort system messages and thinking binding controls. KnightCode persists native effort levels and always sends `drop_block` when enabled. Default: `false`. |
 | `allowEmptySignature` | Whether to replay empty thinking signatures as `signature: ""` instead of converting thinking to text. Default: `false`. |
 | `supportsStrictTools` | Whether the provider accepts strict JSON-schema tool definitions. Default: `false`; built-in Anthropic models enable it in generated metadata. |
+| `allowedFallbackModels` | Up to three server-side fallback models, each with `provider`, `model`, and complete `cost` metadata. An empty array disables fallback. |
 
 ## OpenAI Compatibility
 
@@ -482,7 +483,6 @@ For providers with partial OpenAI compatibility, use the `compat` field.
 | `sessionAffinityFormat` | For `openai-completions` and `openai-responses`, the session-affinity header format: `openai` sends `session_id`/`x-client-request-id` (completions also `x-session-affinity`), `openai-nosession` omits the underscore-containing `session_id` header, `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param. Default: auto-detected. |
 | `supportsStrictMode` | Whether the provider accepts strict JSON-schema function tool definitions. Defaults depend on the API; built-in OpenAI models carry explicit capability metadata. |
 | `supportsOpenAIGrammarTools` | Whether OpenAI-compatible APIs emit custom Lark/regex grammar tools. When `false`, grammar-constrained tools fall back to normal function tools. Default: `false`; the built-in model catalog enables it for GPT-5+ models on OpenAI, OpenAI Codex, Azure OpenAI, GitHub Copilot, opencode, and Cloudflare AI Gateway. |
-| `deferredToolsMode` | Use provider-specific deferred tool serialization. Currently only `"kimi"` is supported for Kimi's OpenAI-compatible Chat Completions format. |
 | `supportsLongCacheRetention` | Whether the provider accepts long cache retention when cache retention is `long`: `prompt_cache_options.ttl: "30m"` for GPT-5.6+ Responses models, `prompt_cache_retention: "24h"` for earlier OpenAI models, or `cache_control.ttl: "1h"` when `cacheControlFormat` is `anthropic`. Default: `true`. |
 | `openRouterRouting` | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection). |
 | `vercelGatewayRouting` | Vercel AI Gateway routing config for provider selection (`only`, `order`) |

package/bin/docs/quickstart.md

@@ -142,7 +142,7 @@ knightcode --name "my task"    # Set session display name at startup
 knightcode --session <path|id> # Open a specific session
 ```
 
-Inside knightcode, use `/resume`, `/new`, `/tree`, `/fork`, and `/clone` to manage sessions.
+Inside knightcode, use `/resume`, `/new`, `/undo`, `/tree`, `/fork`, and `/clone` to manage sessions.
 
 ### Non-interactive mode
 

package/bin/docs/sdk.md

@@ -246,8 +246,8 @@ const state = session.agent.state;
 // state.messages: AgentMessage[] - conversation history
 // state.model: Model - current model
 // state.thinkingLevel: ThinkingLevel - current thinking level
-// state.systemPrompt: string - system prompt
-// state.tools: AgentTool[] - available tools
+// state.systemPrompt: string - read-only, replayed from the transcript's system messages
+// state.tools: AgentTool[] - executable tools; changes are declared to the model before the next request
 // state.streamingMessage?: AgentMessage - current partial assistant message
 // state.errorMessage?: string - latest assistant error
 

package/bin/docs/session-format.md

@@ -77,6 +77,14 @@ interface ToolCall {
 ### Base Message Types (from @knightcode/ai)
 
 ```typescript
+interface SystemMessage {
+  role: "system";
+  content: string | TextContent[];
+  toolsAdded?: Tool[];
+  toolsRemoved?: Array<{ name: string }>;
+  timestamp: number;  // Unix ms
+}
+
 interface UserMessage {
   role: "user";
   content: string | (TextContent | ImageContent)[];
@@ -109,7 +117,6 @@ interface ToolResultMessage {
   content: (TextContent | ImageContent)[];
   details?: any;      // Tool-specific metadata
   usage?: Usage;      // Nested LLM work performed by the tool
-  addedToolNames?: string[];
   isError: boolean;
   timestamp: number;
 }
@@ -177,6 +184,7 @@ interface CompactionSummaryMessage {
 
 ```typescript
 type AgentMessage =
+  | SystemMessage
   | UserMessage
   | AssistantMessage
   | ToolResultMessage
@@ -217,7 +225,14 @@ For sessions with a parent (created via `/fork`, `/clone`, or `newSession({ pare
 
 ### SessionMessageEntry
 
-A message in the conversation. The `message` field contains an `AgentMessage`.
+A message in the conversation. The `message` field contains an `AgentMessage`. System messages carry the prompt and tool loadout: the first request of a session persists one with every prompt section and tool declaration, and later changes persist as system messages that patch `sections` by name (`null` removes one) and list `toolsAdded`/`toolsRemoved`. Replaying them in order yields the current prompt and tools; there is no separate prompt state entry.
+
+```json
+{"type":"message","id":"a0b1c2d3","parentId":null,"timestamp":"2024-12-03T14:00:00.000Z","message":{"role":"system","content":"","sections":{"preamble":"You are an expert coding assistant...","tools":"<tools>\n- read: ...\n</tools>","cwd":"/project"},"toolsAdded":[{"name":"read","description":"...","parameters":{}}],"timestamp":1733234400000}}
+{"type":"message","id":"d4e5f6g7","parentId":"c3d4e5f6","timestamp":"2024-12-03T14:04:00.000Z","message":{"role":"system","content":"","sections":{"skills":"<skills>...</skills>"},"toolsRemoved":[{"name":"write"}],"timestamp":1733234640000}}
+```
+
+Sessions created before system messages existed have no leading system message; the first request declares the current prompt as a later system message, which replays the same way.
 
 ```json
 {"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello","timestamp":1733234401000}}
@@ -243,15 +258,16 @@ Emitted when the user changes the thinking/reasoning level.
 
 ### CompactionEntry
 
-Created when context is compacted. Stores a summary of earlier messages.
+Created when context is compacted. Stores a summary of earlier messages and a complete system prompt/tool checkpoint.
 
 ```json
-{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
+{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000,"systemMessage":{"role":"system","content":"You are a coding assistant.","toolsAdded":[],"timestamp":1733235000000}}
 ```
 
 `firstKeptEntryId` is required. It identifies the first entry retained from before the compaction entry. When rebuilding context, KnightCode replaces older summarized entries with the compaction summary and keeps the range beginning at this entry.
 
 Optional fields:
+- `systemMessage`: The replayed prompt sections and tool declarations at the compaction boundary; it becomes the leading system message of the compacted context, and system messages among the kept entries are dropped in its favor. It is absent on older session entries.
 - `usage`: LLM usage from generating the summary; included in session token and cost totals
 - `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
 - `fromHook`: `true` if generated by an extension, `false`/`undefined` if knightcode-generated (legacy field name)
@@ -336,7 +352,7 @@ Entries normally form one tree, but navigation APIs can create multiple roots:
 1. Collects all entries on the path
 2. If one or more `CompactionEntry` values are on the path, uses the latest one:
    - Includes the compaction entry first
-   - Includes entries from `firstKeptEntryId` up to, but not including, the compaction entry
+   - Includes non-system entries from `firstKeptEntryId` up to, but not including, the compaction entry
    - Includes entries after the compaction entry
 3. Preserves non-message entries in the selected range so interactive mode can render them
 
@@ -345,12 +361,12 @@ Entries normally form one tree, but navigation APIs can create multiple roots:
 1. Extracts current model and thinking level settings from the full path
 2. Converts selected entries to messages:
    - `message` -> stored `AgentMessage`
-   - `compaction` -> `compactionSummary`
+   - `compaction` -> complete system checkpoint followed by `compactionSummary`
    - `branch_summary` -> `branchSummary`
    - `custom_message` -> `CustomMessage`
    - `custom` -> no context message
 
-The compaction summary replaces entries before `firstKeptEntryId`. The retained entries and all entries after the compaction remain available to the LLM.
+The compaction summary replaces entries before `firstKeptEntryId`. Pre-compaction system messages are folded into the complete checkpoint rather than replayed from the retained range. Retained non-system entries and all entries after the compaction remain available to the LLM.
 
 ## Parsing Example
 

package/bin/docs/sessions.md

@@ -28,6 +28,7 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f
 | `/name <name>` | Set the current session display name |
 | `/session` | Show session info |
 | `/tree` | Navigate the current session tree |
+| `/undo` | Go back to an earlier user message, optionally restoring files |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
 | `/compact [prompt]` | Summarize older context; see [Compaction](compaction.md) |
@@ -117,6 +118,40 @@ Selecting an assistant, tool, compaction, or other non-user entry:
 
 Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.
 
+## Undoing with `/undo`
+
+`/undo` is the quick form of `/tree` for the common case: pick a user message on the current
+branch and go back to it. It lists only user messages, newest at the bottom, with the time
+and how many files an undo to that point would restore. Enter goes back; the turns after the
+chosen message are left as an abandoned branch (still reachable through `/tree`) and the
+message text returns to the editor for editing and resubmitting.
+
+### File Restore
+
+Before `edit` or `write` changes a file, KnightCode copies the original into
+`~/.knightcode/agent/file-history/<session id>/`, once per file per user turn. When you go
+back past a turn that changed files, through `/undo`, `/tree`, or double-Escape, you are asked:
+
+- **Conversation only**: files stay as they are.
+- **Conversation and N files**: every file the abandoned turns touched is put back to its
+  content from before those turns; files they created are deleted.
+
+Escape at that prompt cancels the navigation entirely.
+
+Limits:
+
+- Changes made by shell commands (`bash`, `powershell`) are not tracked. The prompt says so
+  when a shell command ran in the abandoned turns.
+- Edits made by subagents or outside KnightCode are not tracked either; a tracked file is
+  restored to its backup regardless of who changed it afterwards.
+- If you go back without restoring files and later go back further, only the edits on the
+  branch you are on are restored.
+- Jumping sideways to another branch with `/tree` restores to the fork point; edits on the
+  target branch are not re-applied.
+
+Backups older than 30 days are removed at startup. Set `KNIGHTCODE_DISABLE_FILE_CHECKPOINTS=1`
+to turn file tracking off; `/undo` then rewinds the conversation only.
+
 ## `/tree`, `/fork`, and `/clone`
 
 | Feature | `/tree` | `/fork` | `/clone` |

package/bin/docs/settings.md

@@ -27,8 +27,8 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `defaultProvider` | string | - | Startup provider (e.g., `"anthropic"`, `"openai"`; saved with Ctrl+S in `/model`, or edited manually) |
-| `defaultModel` | string | - | Startup model ID (saved with Ctrl+S in `/model`, or edited manually) |
+| `defaultProvider` | string | - | Startup provider (e.g., `"anthropic"`, `"openai"`; saved with Ctrl+S in `/model`, by the IDE's model picker, or edited manually) |
+| `defaultModel` | string | - | Startup model ID (saved with Ctrl+S in `/model`, by the IDE's model picker, or edited manually) |
 | `defaultThinkingLevel` | string | - | Startup thinking level (saved with Ctrl+S in `/thinking`, or edited manually): `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` |
 | `modelThinkingLevels` | object | - | Per-model startup thinking levels keyed by `"provider/modelId"`; configure from `/settings` → Default thinking level per model or edit manually |
 | `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
@@ -60,7 +60,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 | `enableInstallTelemetry` | boolean | `true` | Send the anonymous install/update ping and selected provider attribution headers. This does not control update checks |
 | `enableAnalytics` | boolean | `false` | Opt-in analytics data sharing. Currently only asked for during the experimental first-time setup (`KNIGHTCODE_EXPERIMENTAL=1`) |
 | `trackingId` | string | - | Analytics tracking identifier, generated when `enableAnalytics` is turned on |
-| `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
+| `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"`. `/undo` is the quick way to a user message |
 | `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
 | `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |
 | `outputPad` | number | `1` | Horizontal padding for user messages, assistant messages, and thinking (0 or 1) |
@@ -83,6 +83,8 @@ For VS Code, include `--wait` so knightcode resumes after the editor exits:
 
 `enableInstallTelemetry` controls the anonymous install/update ping to `https://knightcode.dev/api/report-install` and KnightCode attribution headers for OpenRouter, NVIDIA NIM, and Cloudflare provider requests. Opting out disables both. It does not disable update checks; KnightCode can still fetch `https://knightcode.dev/api/latest-version` to look for the latest version.
 
+The KnightCode IDE shares this setting rather than keeping its own. Its first run and its settings write `enableInstallTelemetry` here, except while `KNIGHTCODE_TELEMETRY` is set, because the variable outranks the setting. The engine the IDE starts sends the same ping once per IDE version, with a `knightcode-ide` user agent, and records the version it was delivered for as `lastIdeVersion`. A ping that fails is retried on the next start.
+
 Set `KNIGHTCODE_SKIP_VERSION_CHECK=1` to disable the KnightCode version update check. Use `--offline` or `KNIGHTCODE_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.
 
 ### Network
@@ -279,6 +281,8 @@ On Windows, select `powershell` instead of `bash`, or include both:
 
 An empty array starts with no built-in tools while preserving extension and SDK custom tools. `--tools` replaces this behavior with a strict allowlist for all tools, `--no-tools` disables all tools, and `--no-builtin-tools` disables the built-in defaults. `--exclude-tools` filters the resulting list. A project `defaultTools` array replaces the global array.
 
+The [web tools](usage.md#web-tools) `webfetch` and `websearch` are not part of `defaultTools`. `/tools` turns them on and stores their settings, including the search provider and Brave key, in `~/.knightcode/agent/tools.json`.
+
 ### Sessions
 
 | Setting | Type | Default | Description |

package/bin/docs/usage.md

@@ -42,11 +42,13 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/thinking` | Switch thinking level; Ctrl+S or Ctrl+D in the picker saves the startup default |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Theme, message delivery, transport, and other preferences |
+| [`/tools`](#web-tools) | Turn `webfetch` and `websearch` off, on for this session, or on by default; pick the search provider and store its key |
 | `/resume` | Pick from previous sessions |
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |
 | `/session` | Show session file, ID, messages, tokens, and cost |
 | `/tree` | Jump to any point in the session and continue from there |
+| `/undo` | Go back to an earlier user message; optionally restore the files edited after it |
 | `/trust` | Save project trust decision for future sessions |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
@@ -60,6 +62,37 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/changelog` | Display version history |
 | `/quit` | Quit knightcode |
 
+## Web Tools
+
+Two tools give the agent read access to the web. Both ship disabled; turn them on with `/tools`.
+
+| Tool | What it does |
+|------|--------------|
+| `webfetch` | Fetches a URL and returns the page as markdown, 400 lines at a time. The agent pages with `offset`/`limit` like `read`, or passes `grep` to get only matching lines. Responses are cached for 15 minutes, capped at 5 MB, and time out after 30 seconds. Private, loopback, and link-local addresses are refused. |
+| `websearch` | Searches the web and returns up to 10 results (default 5) as title, URL, and snippet. DuckDuckGo needs no key but may rate-limit; Brave Search needs an API key. |
+
+`/tools` lists each tool with its current state; pick one to open its settings panel. **Status** cycles through three states:
+
+| State | Effect |
+|-------|--------|
+| Disabled | The tool is not offered to the model |
+| Enabled for this session | On until knightcode exits, including across `/new`, `/resume`, and `/fork`; nothing is written to disk |
+| Enabled by default | On in every session |
+
+The `websearch` panel adds two rows: **Provider** (`duckduckgo` or `brave`) and **Brave API key**. Choosing Brave without a stored key opens the key prompt at once. Get a key at https://brave.com/search/api/; the free plan is enough. The key is also read from `BRAVE_API_KEY` when none is stored, but the provider only switches to Brave when you pick it. Keys show masked in the panel.
+
+The same changes work without the panel:
+
+```bash
+/tools websearch on        # this session
+/tools webfetch always     # every session
+/tools webfetch off
+```
+
+Settings are stored in `~/.knightcode/agent/tools.json`, owner-readable only because it can hold the Brave key. `--tools` and `--exclude-tools` still apply: a tool excluded on the command line stays off whatever `/tools` says.
+
+Fetched pages and search results are marked as untrusted in the tool output so the model treats instructions inside them as data, but treat the tools like any other network access: a fetched page can still influence what the agent does next.
+
 ## Message Queue
 
 You can submit messages while the agent is still working:
@@ -90,6 +123,7 @@ Useful session commands:
 
 - `/session` shows the current session file and ID.
 - `/tree` navigates the in-file session tree and can summarize abandoned branches.
+- `/undo` goes back to an earlier user message and can restore the files edited after it.
 - `/fork` creates a new session from an earlier user message.
 - `/clone` duplicates the current active branch into a new session file.
 - `/compact` summarizes older messages to free context.
@@ -212,7 +246,7 @@ cat README.md | knightcode -p "Summarize this text"
 | `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
 | `--no-tools`, `-nt` | Disable all tools |
 
-Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`.
+Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`. The [web tools](#web-tools) `webfetch` and `websearch` are off until enabled with `/tools`.
 
 ### Resource Options
 

package/bin/knightcode

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/knightcode
-size: 116660517 bytes
-sha256: 739bf41e41c13fb7f6240996c98de31aaa97659fcf6a790cd6134676fcdb8235
+size: 117489223 bytes
+sha256: c63b1c290333f73c7b200d72bde88f663a23495f1449b8dbe55516a07b5d1d9f

package/bin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "KnightCode — a local, BYOK terminal coding agent powered by OpenRouter.",
   "type": "module",
   "repository": {
@@ -37,11 +37,11 @@
     "test": "vitest --run"
   },
   "optionalDependencies": {
-    "@knightcodeai/cli-linux-x64": "0.7.0",
-    "@knightcodeai/cli-linux-arm64": "0.7.0",
-    "@knightcodeai/cli-darwin-x64": "0.7.0",
-    "@knightcodeai/cli-darwin-arm64": "0.7.0",
-    "@knightcodeai/cli-win32-x64": "0.7.0"
+    "@knightcodeai/cli-linux-x64": "0.9.0",
+    "@knightcodeai/cli-linux-arm64": "0.9.0",
+    "@knightcodeai/cli-darwin-x64": "0.9.0",
+    "@knightcodeai/cli-darwin-arm64": "0.9.0",
+    "@knightcodeai/cli-win32-x64": "0.9.0"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "1.4.0",
@@ -50,6 +50,7 @@
     "@knightcode/client": "workspace:*",
     "@knightcode/protocol": "workspace:*",
     "@knightcode/remote": "workspace:*",
+    "@knightcode/tools": "workspace:*",
     "@knightcode/server": "workspace:*",
     "@knightcode/session-backend-sqlite": "workspace:*",
     "@knightcode/tui": "workspace:*",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli-linux-x64",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "license": "MIT",
   "repository": {
     "type": "git",