@knightcodeai/cli 0.17.3 → 0.18.0

package/docs/security.md

@@ -0,0 +1,99 @@
+# Run KnightCode safely
+
+Treat model-generated commands and code as untrusted. KnightCode can read, change, and execute files with the permissions of the account that started it, and it does not ask for approval before every tool call. Extensions, package installers, language servers, and other child processes run with those same permissions unless an operating-system or virtualization boundary restricts them.
+
+Files, comments, instructions, command output, and model responses can steer the model through prompt injection. Project trust controls which project resources load at startup, but it does not make that content or the resulting actions safe.
+
+Safety comes from limiting the files, credentials, processes, and network services KnightCode can access and affect if a generated action is wrong or hostile. Watching the transcript, using project trust, and reviewing changes do not create a security boundary.
+
+## Choose how to run KnightCode
+
+Different ways of running KnightCode place different limits on what generated commands can access:
+
+| How KnightCode runs | What remains protected |
+|---|---|
+| Directly, with the permissions of its operating-system user | Anything that user cannot access. A dedicated user account can narrow those permissions, but KnightCode still shares the operating system and network with other users. |
+| Entirely inside a container, virtual machine, or sandbox | Host files and processes that you do not expose to the environment. Credentials and network services remain accessible if you make them available inside it. This is usually the strongest practical option. |
+| Outside the isolated environment, with only its built-in tools running inside | Host resources are protected from actions performed through those tools. KnightCode itself and other extensions remain outside the boundary, so this is a narrower form of isolation. |
+
+The working folder controls resource discovery and the default location for tools, but it does not prevent commands from accessing other paths available to the KnightCode process.
+
+Whichever option you choose, only provide the files and services required for the task. Keep credentials outside the environment where possible, or use narrowly scoped, short-lived credentials. Restrict network access when commands do not need it.
+
+For setup instructions and the limitations of each isolation method, see [Run KnightCode in an isolated environment](containerization.md).
+
+<a id="project-trust"></a>
+
+## Understand project trust
+
+Project trust controls whether KnightCode loads most settings and resources supplied by a working folder. It prevents a folder from silently loading executable extensions before you approve it.
+
+Project trust is not a complete startup boundary. KnightCode reads the project `sessionDir` setting while selecting or creating a session, before it resolves project trust. Declining trust prevents the remaining project settings and protected resources from loading, but it cannot undo that initial session-directory lookup.
+
+Project trust does not limit what tool calls can access or affect. After KnightCode starts, enabled tools still use the operating-system permissions of the KnightCode process. Instructions and other content in the folder can also influence the model.
+
+### Resources protected by project trust
+
+KnightCode requires a project-trust decision when it finds any of these resources from the current working directory:
+
+- `.knightcode/settings.json`
+- `.knightcode/mcp.json`
+- `.knightcode/extensions`, `.knightcode/skills`, `.knightcode/prompts`, or `.knightcode/themes`
+- `.knightcode/SYSTEM.md` or `.knightcode/APPEND_SYSTEM.md`
+- project `.agents/skills` in the current directory or an ancestor directory
+
+A bare `.knightcode` directory does not require project trust.
+
+Granting project trust allows KnightCode to load:
+
+- project settings
+- project MCP servers from `.knightcode/mcp.json`
+- extensions, skills, prompt templates, themes, and system-prompt files under `.knightcode`
+- missing packages configured through project settings
+- project-local and project-package extensions
+
+Declining project trust skips those protected resources, except for the initial `sessionDir` lookup described above.
+
+Context files such as `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md` load regardless of project trust unless you disable context loading. Treat instructions in a folder as untrusted input even when you decline project trust.
+
+### How KnightCode chooses a trust decision
+
+A command-line `--approve` or `--no-approve` override applies first. When protected resources exist and there is no command-line override:
+
+1. User-level and command-line extensions can handle the `project_trust` event. The first extension that returns yes or no owns the decision.
+2. If no extension decides, KnightCode looks for a saved decision for the current directory or one of its parents. The closest decision applies.
+3. If no saved decision applies, KnightCode follows the global `defaultProjectTrust` setting, whose default is `"ask"`.
+
+Saved decisions use canonical directory paths and live in:
+
+```text
+~/.knightcode/agent/trust.json
+```
+
+Use `/trust` to save a decision for future KnightCode processes.
+
+### Project trust without an interactive prompt
+
+Print, JSON, and RPC modes cannot show the built-in trust prompt. If no command-line override, extension, or saved decision applies:
+
+- `defaultProjectTrust: "always"` loads protected project resources.
+- `defaultProjectTrust: "ask"` or `"never"` skips them.
+
+Use `--approve` or `--no-approve` when an automated run needs an explicit one-time decision.
+
+## Reduce impact and improve recovery
+
+These practices do not replace isolation, but they reduce exposure or make recovery easier:
+
+- Give KnightCode access only to files and services required for the task.
+- Use snapshots, backups, or version control before substantial changes.
+- Review extensions and packages before loading them. Extensions execute inside the KnightCode process.
+- Prefer narrowly scoped, short-lived credentials.
+- Review diffs and generated output before applying results to another system.
+- Review sessions before exporting or sharing them. They can contain prompts, tool arguments, command output, file contents, and credentials exposed during the conversation.
+
+## Report a security issue
+
+Follow the repository [Security Policy](https://github.com/KnightCodeAI/knightcode/blob/main/SECURITY.md). Do not open a public issue for a security-sensitive report.
+
+Expected local-agent behavior, prompt injection from untrusted content, lack of a built-in sandbox, and behavior from user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a privilege-boundary bypass or access that the local user did not already have.

package/docs/session-format.md

@@ -0,0 +1,358 @@
+# Session File Format
+
+Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with a `type` field. Session entries form a tree structure via `id`/`parentId` fields, enabling in-place branching without creating new files.
+
+For programmatic creation, persistence, and tree navigation, see the [`SessionManager` API](sdk.md#sessionmanager-api).
+
+
+## File Location
+
+```
+~/.knightcode/agent/sessions/--<path>--/<timestamp>_<session-id>.jsonl
+```
+
+By default, `<session-id>` is a UUID. Callers can supply a custom ID through the SDK or `--session-id`. For `<path>`, KnightCode removes the leading path separator and replaces `/`, `\\`, and `:` with `-`.
+
+## Deleting Sessions
+
+Sessions can be removed by deleting their `.jsonl` files under `~/.knightcode/agent/sessions/`.
+
+KnightCode also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, knightcode uses the `trash` CLI to avoid permanent deletion.
+
+## Session Version
+
+Sessions have a version field in the header:
+
+- **Version 1**: Linear entry sequence (legacy, auto-migrated on load)
+- **Version 2**: Tree structure with `id`/`parentId` linking
+- **Version 3**: Renamed `hookMessage` role to `custom` (extensions unification)
+
+Existing sessions are automatically migrated to the current version (v3) when
+opened by an owning manager. Read-only discovery, history, export, and fork-source
+reads do not rewrite or migrate the source file. See [ownership](sessions.md#session-ownership).
+
+## Source Files
+
+Source on GitHub ([knightcode](https://github.com/KnightCodeAI/knightcode)):
+- [`packages/cli/src/core/session-manager.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/core/session-manager.ts) - Session entry types and SessionManager
+- [Message Types](message-types.md) - Shared message and content-block reference
+- [`packages/cli/src/core/messages.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/core/messages.ts) - Extended message types
+- [`packages/ai/src/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/ai/src/types.ts) - Base message and content-block types
+- [`packages/agent/src/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/agent/src/types.ts) - Extensible `AgentMessage` union
+
+For TypeScript definitions in your project, inspect `node_modules/@knightcodeai/cli/dist/` and `node_modules/@knightcode/ai/dist/`.
+
+## Messages
+
+A `message` entry stores an [`AgentMessage`](message-types.md). Message content blocks, roles, usage, and message timestamps are defined in [Message Types](message-types.md).
+
+Session entry timestamps are ISO 8601 strings. The nested message timestamp is a Unix timestamp in milliseconds.
+
+## Entry Base
+
+All entries (except `SessionHeader`) extend `SessionEntryBase`:
+
+```typescript
+interface SessionEntryBase {
+  type: string;
+  id: string;           // Usually an 8-char hex ID; may fall back to a full UUID
+  parentId: string | null;  // Parent entry ID (null for a root entry)
+  timestamp: string;    // ISO timestamp
+}
+```
+
+## Entry Types
+
+### SessionHeader
+
+First line of the file. Metadata only, not part of the tree (no `id`/`parentId`).
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
+```
+
+For sessions with a parent (created via `/fork`, `/clone`, or `newSession({ parentSession })`):
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
+```
+
+### SessionMessageEntry
+
+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}}
+{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:00:02.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"api":"anthropic-messages","provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop","timestamp":1733234402000}}
+{"type":"message","id":"c3d4e5f6","parentId":"b2c3d4e5","timestamp":"2024-12-03T14:00:03.000Z","message":{"role":"toolResult","toolCallId":"call_123","toolName":"bash","content":[{"type":"text","text":"output"}],"isError":false,"timestamp":1733234403000}}
+```
+
+Assistant messages name the model that produced them. Newer messages also record `thinkingLevel`, the KnightCode thinking level requested for that response.
+
+Assistant `durationMs`, when present, measures the reply from its numeric
+`timestamp`; the app server derives final text/reasoning completion times from
+these fields.
+
+### ModelChangeEntry
+
+Emitted when the user switches models mid-session. The latest entry is the selected model, which may be a [virtual model](virtual-models.md); assistant messages then name the physical model that answered.
+
+```json
+{"type":"model_change","id":"d4e5f6g7","parentId":"c3d4e5f6","timestamp":"2024-12-03T14:05:00.000Z","provider":"openai","modelId":"gpt-4o"}
+```
+
+### ThinkingLevelChangeEntry
+
+Emitted when the user changes the thinking/reasoning level.
+
+```json
+{"type":"thinking_level_change","id":"e5f6g7h8","parentId":"d4e5f6g7","timestamp":"2024-12-03T14:06:00.000Z","thinkingLevel":"high"}
+```
+
+### UsageEntry
+
+Records model-attributed usage that is not an assistant message and does not participate in LLM context. `kind` is an arbitrary string identifying the operation; for example, cache warming uses `"cache_warm"`.
+
+```json
+{"type":"usage","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:08:00.000Z","kind":"cache_warm","provider":"anthropic","model":"claude-sonnet-4-5","usage":{"input":0,"output":0,"cacheRead":50000,"cacheWrite":0,"totalTokens":50000,"cost":{"input":0,"output":0,"cacheRead":0.015,"cacheWrite":0,"total":0.015}}}
+```
+
+Usage entries contribute to session token and cost totals. KnightCode hides them from the conversation tree. Consumers should treat unknown `kind` values as normal usage rather than rejecting them.
+
+### CompactionEntry
+
+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,"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. A retain-none compaction stores its own ID in this field, so no preceding entries are retained.
+
+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)
+
+### ContextEditEntry
+
+Append-only edit of one earlier context-producing entry. It changes only future model context; the target entry and its metadata remain unchanged in raw history, UI, exports, and session accounting.
+
+```json
+{"type":"context_edit","id":"g6h7i8j9","parentId":"f6g7h8i9","timestamp":"2024-12-03T14:11:00.000Z","targetId":"c3d4e5f6","replacement":null}
+```
+
+Targets may be user, assistant, tool-result, or custom-message entries. `replacement: null` omits the target from model context. A non-null `replacement` replaces only the target message content. String replacements for assistant and tool-result entries are normalized to one text block because those roles require content arrays. If several edits target the same entry, the latest edit on the active branch wins. Edits are branch-relative: navigating to a point before the edit reveals the target's original contribution again.
+
+### BranchSummaryEntry
+
+Created when switching branches via `/tree` with an LLM generated summary of the left branch up to the common ancestor. Captures context from the abandoned path.
+
+```json
+{"type":"branch_summary","id":"g7h8i9j0","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:15:00.000Z","fromId":"f6g7h8i9","summary":"Branch explored approach A..."}
+```
+
+`parentId` is the entry from which the new branch continues. `fromId` is the previous leaf whose abandoned path was summarized.
+
+Optional fields:
+- `usage`: LLM usage from generating the summary; included in session token and cost totals
+- `details`: File tracking data (`{ 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)
+
+### CustomEntry
+
+Extension state persistence. Does NOT participate in LLM context.
+
+```json
+{"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}
+```
+
+Use `customType` to identify your extension's entries on reload. Interactive mode can render custom entries via `knightcode.registerEntryRenderer(customType, renderer)`, but they still do not participate in LLM context.
+
+KnightCode stores [virtual model](virtual-models.md) router state as custom entries with `customType` `knightcode.virtual-model-state` and `data` `{ provider, modelId, state }`.
+
+#### Turn boundaries
+
+The built-in turn-marker extension writes `knightcode.turn` at the first
+`agent_start` of a run and `knightcode.turnEnd` at `agent_settled`:
+
+```json
+{"type":"custom","id":"turn1234","parentId":"prev1234","timestamp":"2026-10-11T14:00:00.000Z","customType":"knightcode.turn"}
+{"type":"custom","id":"end12345","parentId":"reply123","timestamp":"2026-10-11T14:00:05.000Z","customType":"knightcode.turnEnd","data":{"status":"completed"}}
+```
+
+End status is `completed`, `interrupted`, or `failed`, with optional
+`error: {message, kind}`. Kinds are `auth`, `rateLimit`, `contextOverflow`,
+`network`, `provider`, and `other`, classified from the error text. For example:
+
+```json
+{"type":"custom","id":"end54321","parentId":"reply123","timestamp":"2026-10-11T14:00:05.000Z","customType":"knightcode.turnEnd","data":{"status":"failed","error":{"message":"Too many requests","kind":"rateLimit"}}}
+```
+
+An end entry whose `error` is a plain string reads as
+`{message: <string>, kind: "other"}`. The marker/end-entry timestamps define the app server's final turn
+`startedAt`/`completedAt` in Unix milliseconds.
+
+The marker's entry ID is the [app-server](app-server.md) turn ID. Retries,
+automatic recovery, and steering before settlement share one boundary. A later independent prompt starts another turn. A marker without a
+valid end entry reads as `interrupted`, including after a crash.
+
+Item IDs are deterministic ordinals within the turn, such as
+`turn1234:user:0`, except tool calls, which retain their original call IDs.
+Assistant text/thinking ordinals follow finalized content order; nested calls
+are live-only. Unmarked legacy history is grouped by user-message boundaries
+and uses those entry IDs as turn IDs. Turn markers are custom entries, not a new
+session-file version, and never enter model context.
+
+App-server approval modes use `customType: "knightcode.approvalMode"` with `data`
+of `ask`, `autoEdit`, or `fullAccess`. The latest value on the branch wins;
+malformed stored data restores as `ask` rather than widening access.
+
+#### Plan mode snapshots
+
+The built-in [plan mode](plan-mode.md) writes full snapshots with
+`customType: "plan-mode"`:
+
+```json
+{"type":"custom","id":"plan1234","parentId":"prev1234","timestamp":"2024-12-03T14:20:00.000Z","customType":"plan-mode","data":{"mode":"off","draft":{"revision":2,"markdown":"# Changes\n..."},"approved":2}}
+```
+
+`mode` is `off` or `planning`; `draft` and `approved` are optional. An approved
+revision must equal the draft revision and exist only while off. The latest
+snapshot on the selected branch wins, including entries omitted from model
+context by compaction. Exit and approval retain the draft; entry and submission
+clear approval. Malformed state refuses restoration rather than dropping the
+restrictions. No session version change is needed.
+
+### CustomMessageEntry
+
+Extension-injected messages that DO participate in LLM context.
+
+```json
+{"type":"custom_message","id":"i9j0k1l2","parentId":"h8i9j0k1","timestamp":"2024-12-03T14:25:00.000Z","customType":"my-extension","content":"Injected context...","display":true}
+```
+
+Fields:
+- `content`: String or `(TextContent | ImageContent)[]` (same as UserMessage)
+- `display`: `true` = show in TUI with distinct styling, `false` = hidden
+- `details`: Optional extension-specific metadata (not sent to LLM)
+
+Plan-mode messages use `customType: "plan-mode"`, `display: false`, and
+`details.kind` of `instructions`, `reminder`, `exit`, or `recovery`. Recovery
+also stores `id` (the compaction entry ID), `revision` when present, and `status`
+(`planning` or `approved`). Its content is frozen when appended, so later
+revisions cannot change earlier request content.
+
+### LabelEntry
+
+User-defined bookmark/marker on an entry.
+
+```json
+{"type":"label","id":"j0k1l2m3","parentId":"i9j0k1l2","timestamp":"2024-12-03T14:30:00.000Z","targetId":"a1b2c3d4","label":"checkpoint-1"}
+```
+
+Set `label` to `undefined` to clear a label.
+
+### SessionInfoEntry
+
+Session metadata (e.g., user-defined display name). Set via `/name`, `--name` / `-n`, or `knightcode.setSessionName()` in extensions.
+
+```json
+{"type":"session_info","id":"k1l2m3n4","parentId":"j0k1l2m3","timestamp":"2024-12-03T14:35:00.000Z","name":"Refactor auth module"}
+```
+
+The session name is displayed in the session selector (`/resume`) instead of the first message when set.
+
+## Tree Structure
+
+Entries normally form one tree, but navigation APIs can create multiple roots:
+- A root entry has `parentId: null`; the first entry is initially the root
+- Each non-root entry points to its parent via `parentId`
+- Branching creates new children from an earlier entry
+- The "leaf" is the current position in the tree
+- Calling `resetLeaf()` or `branchWithSummary(null, ...)` allows a later entry to become another root
+
+```
+[user msg] ─── [assistant] ─── [user msg] ─── [assistant] ─┬─ [user msg] ← current leaf
+                                                            │
+                                                            └─ [branch_summary] ─── [user msg] ← alternate branch
+```
+
+## Context Building
+
+`buildContextEntries()` walks from the current leaf to the root, producing the active entry list while honoring compaction:
+
+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 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
+
+`buildSessionProjection()` then applies the latest `context_edit` for each selected target. It returns the model-visible messages together with their source entries. Omitted targets produce no message; replacements retain the source entry's role and metadata while changing only content. The raw selected entries are not modified.
+
+`buildSessionContext()` builds on that projection to produce the message list for the LLM:
+
+1. Extracts current model and thinking level settings from the full path
+2. Converts selected entries to messages:
+   - `message` -> stored `AgentMessage`
+   - `compaction` -> complete system checkpoint followed by `compactionSummary`
+   - `branch_summary` -> `branchSummary`
+   - `custom_message` -> `CustomMessage`
+   - `context_edit` -> no context message of its own
+   - `usage` and `custom` -> no context message
+
+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
+
+```typescript
+import { readFileSync } from "fs";
+
+const lines = readFileSync("session.jsonl", "utf8").trim().split("\n");
+
+for (const line of lines) {
+  const entry = JSON.parse(line);
+
+  switch (entry.type) {
+    case "session":
+      console.log(`Session v${entry.version ?? 1}: ${entry.id}`);
+      break;
+    case "message":
+      console.log(`[${entry.id}] ${entry.message.role}: ${JSON.stringify(entry.message.content)}`);
+      break;
+    case "compaction":
+      console.log(`[${entry.id}] Compaction: ${entry.tokensBefore} tokens summarized`);
+      break;
+    case "branch_summary":
+      console.log(`[${entry.id}] Branch from ${entry.fromId}`);
+      break;
+    case "usage":
+      console.log(`[${entry.id}] Usage (${entry.kind}): ${entry.usage.totalTokens} tokens`);
+      break;
+    case "custom":
+      console.log(`[${entry.id}] Custom (${entry.customType}): ${JSON.stringify(entry.data)}`);
+      break;
+    case "custom_message":
+      console.log(`[${entry.id}] Extension message (${entry.customType}): ${entry.content}`);
+      break;
+    case "label":
+      console.log(`[${entry.id}] Label "${entry.label}" on ${entry.targetId}`);
+      break;
+    case "model_change":
+      console.log(`[${entry.id}] Model: ${entry.provider}/${entry.modelId}`);
+      break;
+    case "thinking_level_change":
+      console.log(`[${entry.id}] Thinking: ${entry.thinkingLevel}`);
+      break;
+  }
+}
+```

package/docs/sessions.md

@@ -0,0 +1,135 @@
+# Sessions and Context
+
+KnightCode saves a conversation as a session. The active branch of that session supplies conversation history for the next model request. Use session commands to continue work, explore another branch, or reduce the amount of history sent to the model.
+
+## Continue or switch sessions
+
+KnightCode saves sessions automatically unless you start it with `--no-session`.
+
+```bash
+knightcode --continue
+knightcode --resume
+```
+
+`--continue` opens the most recent session for the current working directory. `--resume` opens the session picker. In interactive mode, `/resume` opens the same picker and `/new` starts a new session.
+
+Use `/name` or `--name` to assign a recognizable session name. Run `/session` to verify the current session file, ID, message count, token usage, and cost.
+
+The session picker lets you search, rename, and delete sessions. It can also show paths, change sorting, and limit results to named sessions. See [Keybindings](keybindings.md#sessions) for its shortcuts.
+
+## Choose how to branch
+
+KnightCode stores entries as a tree, so returning to an earlier point does not erase the branch you leave.
+
+| Action | Result | Use it when |
+|---|---|---|
+| `/tree` | Moves within the current session file | Related alternatives should stay together |
+| `/fork` | Creates a new session from an earlier user message | The alternative should become separate work |
+| `/clone` | Copies the active branch into a new session | You want a separate copy of the current state |
+| `/undo` | Returns to an earlier user message on the current branch, optionally restoring files | You want to take back the last turns |
+
+In `/tree`, select a user message to put its text back in the editor. Edit and submit it to create another branch. Selecting an assistant response or another entry continues after that entry with an empty editor.
+
+<p align="center"><img src="images/tree-view.png" alt="The /tree view showing a session with two branches, user messages, assistant replies, and tool calls" width="750"></p>
+
+Selecting a point while the model is responding cancels that response. Navigation cannot proceed while compaction or another tree navigation is still running; wait for it to finish and retry.
+
+When you leave a branch, KnightCode can summarize it and attach that summary to the branch you enter. This preserves relevant work from the abandoned path without including every message from it.
+
+For the persisted tree and entry types, see [Session Format](session-format.md).
+
+## 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. `/undo` never summarizes the
+branch it leaves.
+
+### 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.
+
+## Manage conversation context
+
+The model receives the active branch, not every branch in the session file. KnightCode combines that history with the system prompt, discovered context files, available tools, and loaded skill descriptions. [How KnightCode Works](how-knightcode-works.md#context) describes how those inputs are assembled.
+
+The footer shows current context usage. When the active context approaches the model's limit, KnightCode normally compacts older history automatically. Compaction adds a summary and keeps recent messages. It does not delete the original session entries.
+
+Run `/compact` to compact manually. You can add instructions when the summary should preserve a particular topic or decision. Configure automatic compaction and retained history through [Settings](settings.md#compaction).
+
+Compaction can fail if the provider is unavailable or cannot accept the summarization request. Correct the provider problem and run `/compact` again. Disabling automatic compaction does not disable the manual command.
+
+See [Compaction Reference](compaction.md) for thresholds, retained boundaries, branch-summary behavior, and extension hooks.
+
+## Control session storage
+
+By default, KnightCode stores sessions under `~/.knightcode/agent/sessions/`, grouped by working directory. Use `--session-dir`, `KNIGHTCODE_CODING_AGENT_SESSION_DIR`, or the `sessionDir` setting to choose another location. The CLI option has highest precedence.
+
+Use `--no-session` for an ephemeral run. An ephemeral session cannot be resumed after KnightCode exits.
+
+Use `--session` when you already know the session path or ID. Use `--fork` to create a new session from an existing session before interactive mode starts.
+
+## Session ownership
+
+Only one KnightCode process may write a persisted session at a time. Opening a
+session locks its canonical file path and canonical parent directory binding.
+Symlink and Windows junction aliases identify the same file; hard-linked
+transcripts are refused because distinct names could bypass ownership. Managers
+inside one process share counted ownership; the final `close()` releases it.
+
+If another terminal or the [app server](app-server.md) owns the session, terminal
+startup and `/resume` offer to continue in a fork. Accepting reads the source
+without changing it and creates an independently owned transcript. Declining
+keeps the current interactive session. Non-interactive invocations fail rather
+than waiting for input.
+
+Locks are refreshed while live. After a crashed or stalled owner's lock expires,
+another process can take it. The old owner detects this before writes, refuses
+mutations, and never removes the new owner's lock. Read-only listings, exports,
+history reads, and fork-source reads need no ownership and never repair or migrate
+the source. Repairs and migrations happen only when an owner opens it.
+
+Closing a persisted manager is final: it remains readable but cannot write again.
+Reopen through a new `SessionManager.open()` after closing or disposing its
+session. See the [SDK ownership example](sdk.md#session-ownership).
+
+App-server archive/unarchive operations own both source and destination until
+publication and lookup updates finish. They refuse collisions, publish without
+replacement, and report recovery paths if a move cannot finish; they do not
+silently overwrite another transcript.
+
+## Export or share a session
+
+Use `/export` to write the current session as HTML or JSONL. Use `/share` to upload it and get a viewer link. By default, KnightCode uses a Radius artifact when Radius authentication is configured; otherwise, it uses a private GitHub gist. Set [`sessionShareDestination`](settings.md#sessions-and-context) to `gist` or `radius` to force one destination.
+
+Review exported or shared sessions first. They can contain prompts, model responses, tool arguments, command output, file contents, and extension messages.
+
+## Report a bug
+
+Run `/bug [description]` to prepare a private report for the KnightCode maintainers. You can include the session transcript, omit it, or ask the current model to summarize the problem. Review any transcript or generated summary because it can contain sensitive conversation data.
+
+The report includes environment and provider configuration without credential values, plus recorded error diagnostics. Upload it to the maintainers through `remote.knightcode.dev` or export the same report as a zip to inspect and share yourself. Uploads do not require a login and are always anonymous. If an upload fails, KnightCode offers to export the zip.