@diffexai/diffex 0.2.4 → 0.2.6

package/docs/security.md

@@ -1,66 +0,0 @@
-# Security
-
-Diffex is a local coding agent. It runs with the permissions of the user account that starts it, and it treats files writable by that user as inside the same local trust boundary.
-
-## Project Trust
-
-Project trust controls whether Diffex loads project-local settings, resources, packages, and extensions. It is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory.
-
-Diffex considers a project to have resources that require trust when it finds any of these from the current working directory:
-
-- `.diffex/settings.json`
-- `.diffex/extensions`, `.diffex/skills`, `.diffex/prompts`, or `.diffex/themes`
-- `.diffex/SYSTEM.md` or `.diffex/APPEND_SYSTEM.md`
-- project `.agents/skills` in the current directory or an ancestor directory
-
-A bare `.diffex` directory does not count as a project resource that requires trust.
-
-When an interactive session starts in a project with resources that require trust and no saved decision for the current directory or a parent directory, Diffex follows `defaultProjectTrust` from global settings. The default value is `"ask"`, which asks whether to trust the project when UI is available. Saved decisions are stored by canonical directory in `~/.diffex/agent/trust.json`, and the closest saved decision on the current or parent path applies before the global default.
-
-Trusting a project allows Diffex to load project resources that require trust, including:
-
-- `.diffex/settings.json`
-- `.diffex` resources such as extensions, skills, prompt templates, themes, and system prompt files
-- missing project packages configured through project settings
-- project-local extensions and project package-managed extensions
-
-Declining trust skips protected resources. Context files such as `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md` are loaded regardless of project trust unless context loading is disabled. Before trust is resolved, Diffex only loads context files, user/global extensions, and CLI `-e` extensions. User/global and CLI extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision.
-
-Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, `defaultProjectTrust: "ask"` and `"never"` ignore such resources, while `"always"` trusts them. Use `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
-
-## No Built-in Sandbox
-
-Diffex does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the Diffex process. Extensions are TypeScript modules that run with the same permissions. Package installs, shell commands, language servers, test commands, and other developer tools behave as ordinary local processes.
-
-This is intentional. Diffex is designed to operate on local source trees, invoke project toolchains, and integrate with the user's existing development environment. A partial in-process sandbox would be easy to misunderstand as a security boundary while still depending on the host shell, filesystem, package managers, credentials, and extension code. Real isolation needs to come from the operating system or a virtualization/container boundary.
-
-Project trust is only an input-loading guard. It prevents a repository from silently changing Diffex's settings or extensions before you approve it. It does not make untrusted code, untrusted prompts, or untrusted model output safe. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by Diffex.
-
-## Running Untrusted or Unmonitored Work
-
-For untrusted repositories, generated code you do not intend to monitor closely, or unattended automation, run Diffex in a contained environment. Use a container, VM, micro-VM, remote sandbox, or policy-controlled sandbox with only the files and credentials required for the task.
-
-Common patterns are documented in [Containerization](containerization.md):
-
-- run the whole Diffex process inside a container/sandbox
-- mount only the workspace paths the agent should access
-- avoid mounting host `~/.diffex/agent` unless the container should access host sessions, settings, and credentials
-- pass the minimum required API keys or use short-lived credentials
-- restrict network access when the task does not need it
-- review diffs and outputs before copying results back to trusted systems
-
-If you bind-mount a host workspace read/write, writes from inside the container or VM can still modify host files. Use read-only mounts or copy files into and out of the sandbox when you need stronger protection from unintended writes.
-
-## Evolution Data and Generated Skills
-
-Invocation traces, evolution artifacts and failures, candidate history, lifecycle observations, writer receipts, and harness revisions persist beneath the effective agent directory. They can contain session evidence, generated instructions, skill content, paths, and runtime metadata. Evolution model calls may consume provider quota.
-
-Evolved skills are generated instructions and can direct the model to use tools or referenced assets. Structural, provenance, scope, and security validation reduce risk but do not prove semantic safety and are not a sandbox. Retrieval and behavioral evaluation is temporarily skipped when no evaluator is configured, so those candidates have not been checked for retrieval quality, behavior improvement, misapplication, or regressions. Project trust does not sandbox an already selected harness revision.
-
-Review `/evolve` provenance, draft diffs, validation, whether evaluation ran or was skipped, and the complete generated package before activation. Use `/version` and rollback controls to select immutable revisions, and use OS or container isolation for unattended work. See [Harness Evolution](evolution.md).
-
-## Reporting Security Issues
-
-To report a security issue, follow the repository [Security Policy](https://github.com/diffexai/diffex/blob/main/SECURITY.md). Do not open a public issue for security-sensitive reports.
-
-Expected local-agent behavior, lack of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a real privilege-boundary bypass or shows how Diffex grants access that the local user did not already have.

package/docs/session-format.md

@@ -1,438 +0,0 @@
-# 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.
-
-## File Location
-
-```
-~/.diffex/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
-```
-
-Where `<path>` is the working directory with `/` replaced by `-`.
-
-## Deleting Sessions
-
-Sessions can be removed by deleting their `.jsonl` files under `~/.diffex/agent/sessions/`.
-
-Diffex also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, Diffex 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 loaded.
-
-## Source Files
-
-Source on GitHub ([diffex](https://github.com/diffexai/diffex)):
-- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/diffexai/diffex/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
-- [`packages/coding-agent/src/core/messages.ts`](https://github.com/diffexai/diffex/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
-- [`packages/ai/src/types.ts`](https://github.com/diffexai/diffex/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
-- [`packages/agent/src/types.ts`](https://github.com/diffexai/diffex/blob/main/packages/agent/src/types.ts) - AgentMessage union type
-
-For TypeScript definitions in your project, inspect `node_modules/@diffexai/diffex/dist/` and `node_modules/@diffexai/diffex-ai/dist/`.
-
-## Message Types
-
-Session entries contain `AgentMessage` objects. Understanding these types is essential for parsing sessions and writing extensions.
-
-### Content Blocks
-
-Messages contain arrays of typed content blocks:
-
-```typescript
-interface TextContent {
-  type: "text";
-  text: string;
-}
-
-interface ImageContent {
-  type: "image";
-  data: string;      // base64 encoded
-  mimeType: string;  // e.g., "image/jpeg", "image/png"
-}
-
-interface ThinkingContent {
-  type: "thinking";
-  thinking: string;
-}
-
-interface ToolCall {
-  type: "toolCall";
-  id: string;
-  name: string;
-  arguments: Record<string, any>;
-}
-```
-
-### Base Message Types (from diffex-ai)
-
-```typescript
-interface UserMessage {
-  role: "user";
-  content: string | (TextContent | ImageContent)[];
-  timestamp: number;  // Unix ms
-}
-
-interface AssistantMessage {
-  role: "assistant";
-  content: (TextContent | ThinkingContent | ToolCall)[];
-  api: string;
-  provider: string;
-  model: string;
-  usage: Usage;
-  stopReason: "stop" | "length" | "toolUse" | "error" | "aborted";
-  errorMessage?: string;
-  timestamp: number;
-}
-
-interface ToolResultMessage {
-  role: "toolResult";
-  toolCallId: string;
-  toolName: string;
-  content: (TextContent | ImageContent)[];
-  details?: any;      // Tool-specific metadata
-  usage?: Usage;      // Nested LLM work performed by the tool
-  isError: boolean;
-  timestamp: number;
-}
-
-interface Usage {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  totalTokens: number;
-  cost: {
-    input: number;
-    output: number;
-    cacheRead: number;
-    cacheWrite: number;
-    total: number;
-  };
-}
-```
-
-The exported diffex-ai `StopReason` type also includes `"pending"`, but that value is reserved for partial messages in streaming events. Terminal `done`/`error` messages replace it with a completion reason before Diffex persists the assistant message, so `"pending"` should never appear in session JSONL.
-
-### Extended Message Types (from diffex-coding-agent)
-
-```typescript
-interface BashExecutionMessage {
-  role: "bashExecution";
-  command: string;
-  output: string;
-  exitCode: number | undefined;
-  cancelled: boolean;
-  truncated: boolean;
-  fullOutputPath?: string;
-  excludeFromContext?: boolean;  // true for !! prefix commands
-  timestamp: number;
-}
-
-interface CustomMessage {
-  role: "custom";
-  customType: string;            // Extension identifier
-  content: string | (TextContent | ImageContent)[];
-  display: boolean;              // Show in TUI
-  details?: any;                 // Extension-specific metadata
-  timestamp: number;
-}
-
-interface BranchSummaryMessage {
-  role: "branchSummary";
-  summary: string;
-  fromId: string;                // Entry we branched from
-  timestamp: number;
-}
-
-interface CompactionSummaryMessage {
-  role: "compactionSummary";
-  summary: string;
-  tokensBefore: number;
-  timestamp: number;
-}
-```
-
-### AgentMessage Union
-
-```typescript
-type AgentMessage =
-  | UserMessage
-  | AssistantMessage
-  | ToolResultMessage
-  | BashExecutionMessage
-  | CustomMessage
-  | BranchSummaryMessage
-  | CompactionSummaryMessage;
-```
-
-## Entry Base
-
-All entries (except `SessionHeader`) extend `SessionEntryBase`:
-
-```typescript
-interface SessionEntryBase {
-  type: string;
-  id: string;           // 8-char hex ID
-  parentId: string | null;  // Parent entry ID (null for first 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`.
-
-```json
-{"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello"}}
-{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:00:02.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop"}}
-{"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}}
-```
-
-### ModelChangeEntry
-
-Emitted when the user switches models mid-session.
-
-```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"}
-```
-
-### CompactionEntry
-
-Created when context is compacted. Stores a summary of earlier messages.
-
-```json
-{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
-```
-
-Newer harness-generated compactions embed the retained post-compaction context directly on the entry, instead of `firstKeptEntryId`:
-
-```json
-{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","tokensBefore":50000,"retainedTail":[{"role":"user","content":"latest request"},{"role":"assistant","content":[{"type":"text","text":"latest reply"}],"provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop"}]}
-```
-
-Optional fields:
-- `usage`: LLM usage from generating the summary; included in session token and cost totals
-- `retainedTail`: Materialized `AgentMessage[]` kept after compaction. This is optional only for backward compatibility with older sessions. Newer harness-generated compactions include it so we can rebuild context from this checkpoint without walking older entries before the compaction entry.
-- `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 Diffex-generated (legacy field name)
-- `firstKeptEntryId`: for compatibility with old entry format.
-
-### 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..."}
-```
-
-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 Diffex-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 `diffex.registerEntryRenderer(customType, renderer)`, but they still do not participate in LLM context.
-
-### 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)
-
-### 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 `diffex.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 form a tree:
-- First entry has `parentId: null`
-- Each subsequent entry points to its parent via `parentId`
-- Branching creates new children from an earlier entry
-- The "leaf" is the current position in the tree
-
-```
-[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 a `CompactionEntry` is on the path:
-   - Includes the compaction entry first
-   - If `retainedTail` is present, it acts as a self-contained checkpoint and entries after the compaction are included
-   - Otherwise entries from `firstKeptEntryId` to the compaction are included
-   - Then entries after compaction are included
-3. Preserves non-message entries in the selected range so interactive mode can render them
-
-`buildSessionContext()` builds on that entry list 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` -> `compactionSummary` plus `retainedTail` when present
-   - `branch_summary` -> `branchSummary`
-   - `custom_message` -> `CustomMessage`
-   - `custom` -> no context message
-
-This makes newer compactions act like self-contained checkpoints. `retainedTail` is optional only so older sessions that only store `firstKeptEntryId` continue to load correctly.
-
-## 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 "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;
-  }
-}
-```
-
-## SessionManager API
-
-Key methods for working with sessions programmatically.
-
-### Static Creation Methods
-- `SessionManager.create(cwd, sessionDir?)` - New session
-- `SessionManager.open(path, sessionDir?)` - Open existing session file
-- `SessionManager.continueRecent(cwd, sessionDir?)` - Continue most recent or create new
-- `SessionManager.inMemory(cwd?)` - No file persistence
-- `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)` - Fork session from another project
-
-### Static Listing Methods
-- `SessionManager.list(cwd, sessionDir?, onProgress?)` - List sessions for a directory
-- `SessionManager.listAll(onProgress?)` - List all sessions across all projects
-
-### Instance Methods - Session Management
-- `newSession(options?)` - Start a new session (options: `{ parentSession?: string }`)
-- `setSessionFile(path)` - Switch to a different session file
-- `createBranchedSession(leafId)` - Extract branch to new session file
-
-### Instance Methods - Appending (all return entry ID)
-- `appendMessage(message)` - Add message
-- `appendThinkingLevelChange(level)` - Record thinking change
-- `appendModelChange(provider, modelId)` - Record model change
-- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add compaction
-- `appendCustomEntry(customType, data?)` - Extension state (not in context)
-- `appendSessionInfo(name)` - Set session display name
-- `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
-- `appendLabelChange(targetId, label)` - Set/clear label
-
-### Instance Methods - Tree Navigation
-- `getLeafId()` - Current position
-- `getLeafEntry()` - Get current leaf entry
-- `getEntry(id)` - Get entry by ID
-- `getBranch(fromId?)` - Walk from entry to root
-- `getTree()` - Get full tree structure
-- `getChildren(parentId)` - Get direct children
-- `getLabel(id)` - Get label for entry
-- `branch(entryId)` - Move leaf to earlier entry
-- `resetLeaf()` - Reset leaf to null (before any entries)
-- `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
-
-### Instance Methods - Context & Info
-- `buildContextEntries()` - Get active branch entries with compaction applied
-- `buildSessionContext()` - Get messages, thinkingLevel, and model for LLM
-- `getEntries()` - All entries (excluding header)
-- `getHeader()` - Session header metadata
-- `getSessionName()` - Get display name from latest session_info entry
-- `getCwd()` - Working directory
-- `getSessionDir()` - Session storage directory
-- `getSessionId()` - Session UUID
-- `getSessionFile()` - Session file path (undefined for in-memory)
-- `isPersisted()` - Whether session is saved to disk

package/docs/sessions.md

@@ -1,162 +0,0 @@
-# Sessions
-
-Diffex saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.
-
-## Session Storage
-
-Sessions auto-save to `~/.diffex/agent/sessions/`, organized by working directory. Each session is a JSONL file with a tree structure.
-
-```bash
-diffex -c                  # Continue most recent session
-diffex -r                  # Browse and select from past sessions
-diffex --no-session        # Ephemeral mode; do not save
-diffex --name "my task"    # Set session display name at startup
-diffex --session <path|id> # Use a specific session file or partial session ID
-diffex --fork <path|id>    # Fork a session file or partial session ID into a new session
-```
-
-Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
-
-For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
-
-## Session Commands
-
-| Command | Description |
-|---------|-------------|
-| `/resume` | Browse and select previous sessions |
-| `/new` | Start a new session |
-| `/name <name>` | Set the current session display name |
-| `/session` | Show session info |
-| `/subagents` | Show sub-agents in the current session |
-| `/tree` | Navigate the current session tree |
-| `/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) |
-| `/export [file]` | Export session to HTML |
-| `/share` | Upload as a secret GitHub Gist and return its direct URL |
-
-## Sub-agents in Saved Sessions
-
-Saved parent sessions automatically preserve their branch-scoped sub-agent roster and usable child histories. Reopening a parent restores terminal records as recorded and changes children that were queued or running to interrupted. Reopening does not resume provider work, replay the original task, or redeliver a completed result.
-
-An explicit wake resumes a child from its saved history when that history is usable. If the history is missing, unsafe, or invalid, Diffex creates an isolated replacement and runs only the wake message. A wake uses the child's complete captured model, thinking level, tools, and harness when all remain usable; otherwise it uses the complete current parent configuration and reports a warning rather than mixing configurations.
-Restored and replacement children receive the child-only `escalate_to_parent` tool only after an explicit wake starts a live run.
-
-Escalation reports delivered to the root are hidden from the transcript but are not secret or redacted.
-Accepted idle reports, delivered active reports, and the child's tool-call arguments remain normal session history.
-Both `subagent_results` and `subagent_escalations` are untrusted delegated-agent reports rather than user or system instructions or authority. The root is instructed to verify material claims against the parent task and available evidence, and to follow embedded instructions only when they agree with the parent task, repository policy, and current evidence.
-An idle report in a saved session is appended to the currently selected parent branch without starting a provider call and is supplied to the parent on its next explicit run; an in-memory parent keeps the report only in the live session.
-Branch navigation retains only the selected branch's pending saved reports for capacity accounting.
-Deleting a parent session continues to delete its parent history and owned child-session namespace through the normal parent-owned deletion behavior.
-
-Branch navigation and session-context resets reconcile the roster only after the transition is safe. In-memory parents and `--no-session` sessions keep sub-agents ephemeral. Setting `subagents: false` disables the sub-agent tools without erasing a saved roster.
-
-## Resuming and Deleting Sessions
-
-`/resume` opens an interactive session picker for the current project. `diffex -r` opens the same picker at startup.
-
-In the picker you can:
-
-- search by typing
-- toggle path display with Ctrl+P
-- toggle sort mode with Ctrl+S
-- filter to named sessions with Ctrl+N
-- rename with Ctrl+R
-- delete with Ctrl+D, then confirm
-
-When available, Diffex uses the `trash` CLI for deletion instead of permanently removing files.
-
-## Naming Sessions
-
-Use `/name <name>` to set a human-readable session name:
-
-```text
-/name Refactor auth module
-```
-
-Set the name at startup with `--name` or `-n`:
-
-```bash
-diffex --name "Refactor auth module"
-diffex --name "CI audit" -p "Review this build failure"
-```
-
-Named sessions are easier to find in `/resume` and `diffex -r`.
-
-## Branching with `/tree`
-
-Sessions are stored as trees. Every entry has an `id` and `parentId`, and the current position is the active leaf. `/tree` lets you jump to any previous point and continue from there without creating a new file.
-
-<p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>
-
-Example shape:
-
-```text
-├─ user: "Hello, can you help..."
-│  └─ assistant: "Of course! I can..."
-│     ├─ user: "Let's try approach A..."
-│     │  └─ assistant: "For approach A..."
-│     │     └─ user: "That worked..."  ← active
-│     └─ user: "Actually, approach B..."
-│        └─ assistant: "For approach B..."
-```
-
-### Tree Controls
-
-| Key | Action |
-|-----|--------|
-| ↑/↓ | Navigate visible entries |
-| ←/→ | Page up/down |
-| Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold or jump between branch segments |
-| Shift+L | Set or clear a label on the selected entry |
-| Shift+T | Toggle label timestamps |
-| Enter | Select entry |
-| Escape/Ctrl+C | Cancel |
-| Ctrl+O | Cycle filter mode |
-
-Filter modes are: default, no-tools, user-only, labeled-only, and all. Configure the default with `treeFilterMode` in [Settings](settings.md).
-
-### Selection Behavior
-
-Selecting a user or custom message:
-
-1. Moves the leaf to the selected message's parent.
-2. Places the selected message text in the editor.
-3. Lets you edit and resubmit, creating a new branch.
-
-Selecting an assistant, tool, compaction, or other non-user entry:
-
-1. Moves the leaf to that entry.
-2. Leaves the editor empty.
-3. Lets you continue from that point.
-
-Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.
-
-## `/tree`, `/fork`, and `/clone`
-
-| Feature | `/tree` | `/fork` | `/clone` |
-|---------|---------|---------|----------|
-| Output | Same session file | New session file | New session file |
-| View | Full tree | User-message selector | Current active branch |
-| Typical use | Explore alternatives in place | Start a new session from an earlier prompt | Duplicate current work before continuing |
-| Summary | Optional branch summary | None | None |
-
-Use `/tree` when you want to keep alternatives together. Use `/fork` or `/clone` when you want a separate session file.
-
-## Branch Summaries
-
-When `/tree` switches away from one branch to another, Diffex can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.
-
-When prompted, choose one of:
-
-1. no summary
-2. summarize with the default prompt
-3. summarize with custom focus instructions
-
-See [Compaction](compaction.md) for branch summarization internals and extension hooks.
-
-## Session Format
-
-Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
-
-For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](session-format.md).