savant-code 0.0.19 → 0.0.20

package/docs/reports/repos/opencode-dev.md

@@ -1,78 +0,0 @@
-# OpenCode — Feature Inventory
-
-> **Repo:** `resources/opencode-dev` | **Stack:** TypeScript/Bun + Effect-TS
-> **Nature:** Kilo Code's upstream project
-
-## Overview
-
-OpenCode is the upstream project for Kilo Code. It is a TypeScript/Bun coding agent built on the Effect-TS library with a four-axis LLM route architecture, durable session runner, session input delivery (steer/queue), system context algebra, and content-addressed snapshots. It is one of the most architecturally principled coding agents.
-
-## Feature Inventory
-
-### LLM Provider System
-
-- **Four-Axis Route Architecture** — Protocol (API contract), Endpoint (URL), Auth (credentials), Framing (stream decoding). DeepSeek, TogetherAI, Cerebras all reuse `OpenAIChat.protocol` — 5-15 lines per new provider. (`packages/llm/src/route/protocol.ts`, `endpoint.ts`, `auth.ts`, `framing.ts`)
-- **Schema-First Data Model** — All LLM types as Effect Schema classes. Compile-time type safety + runtime validation + JSON encoding. (`packages/llm/src/schema/`)
-- **Typed Tool Runtime** — `ToolRuntime.dispatch` decodes input against schema, dispatches, encodes output. Provider-defined tools pass through untouched. (`packages/llm/src/tool-runtime.ts`)
-
-### Session Management
-
-- **Durable Session Runner** — Runs one session until it settles. Loads history, resolves model, assembles system context, streams exactly one LLM turn, persists events incrementally, settles tools durably, loops. (`packages/core/src/session/runner/llm.ts`)
-- **Session Input Delivery (Steer/Queue)** — `steer`: promoted at next safe boundary, resets step count. `queue`: pending until idle, one promoted per boundary. Prevents race conditions. (`packages/core/src/session/input.ts`)
-- **Session Context Epoch** — Tracks when system context was last reconciled. Changes injected as durable updates at safe boundaries. (`packages/core/src/session/context-epoch.ts`)
-- **Session Compaction** — Structured Markdown summary (Objective, Important Details, Work State, Next Move, Relevant Files). Tool output truncated to 2000 chars. (`packages/core/src/session/compaction.ts`)
-- **Session Revert** — Captures snapshots, restores filesystem state. Stage preview then execute. (`packages/core/src/session/revert.ts`)
-
-### System Context
-
-- **System Context Algebra** — `Source<A>` with key, codec, load function, baseline/update/remove renderers. Composed into `SystemContext`, observed once for durable `Snapshot`. Prevents context drift. (`packages/core/src/system-context/`)
-
-### Tool System
-
-- **Tool.define Pattern** — `Tool.make({ description, input, output, execute, toModelOutput })`. Layered registration: Location > Application. Scoped lifecycle with `Effect.addFinalizer`. (`packages/core/src/tool/tool.ts`, `registry.ts`)
-- **Tool Output Store** — 2000 lines, 50KB limit. Head/tail preview sampling. 7-day retention. (`packages/core/src/tool-output-store.ts`)
-
-### Permission System
-
-- **Wildcard Pattern Matching** — `allow/deny/ask` with `Wildcard.match`. Saved approvals. Config protection. (`packages/opencode/src/permission/evaluate.ts`)
-
-### Agent System
-
-- **Dual-Agent** — `build` (full-access) and `plan` (read-only). `general` subagent for complex searches. Tab to switch. Agent step limits with forced summary. (`packages/opencode/src/agent/agent.ts`)
-
-### Plugin System
-
-- **Comprehensive Hooks** — `event`, `config`, `tool`, `auth`, `provider`, `chat.message`, `chat.params`, `chat.headers`, `permission.ask`, `tool.execute.before`, `tool.execute.after`, `shell.env`, `experimental.chat.system.transform`, `experimental.session.compacting`. (`packages/plugin/src/index.ts`)
-
-### MCP Integration
-
-- **Full Client** — Stdio, SSE, Streamable HTTP transports. OAuth provider and callback. Browser-based flows. Catalog management. (`packages/opencode/src/mcp/`)
-
-### Snapshot System
-
-- **Content-Addressed** — Efficient deduplication. Diff between snapshots, preview restore, selective path restoration. 7-day retention. (`packages/core/src/snapshot.ts`)
-
-### Other
-
-- **Durable Event System (EventV2)** — SQLite-backed, replayable event store with aggregate sequence tracking. (`packages/core/src/event.ts`)
-- **Background Job System** — Status tracking, output streaming, promotion (background → foreground), timeout. (`packages/core/src/background-job.ts`)
-- **PTY Management** — Create, update, attach, detach. Subscriber-based data streaming with cursor tracking. 2MB cap. (`packages/core/src/pty.ts`)
-- **LSP Integration** — Diagnostics, symbol lookup, document symbols, status tracking. (`packages/opencode/src/lsp/`)
-- **IAM-Style Policy Engine** — Wildcard-pattern-matched statements. Last match wins. (`packages/core/src/policy.ts`)
-- **Skill Discovery** — Remote URLs with concurrent fetching (4 skill, 8 file concurrency). Path validation. (`packages/core/src/skill/discovery.ts`)
-- **Filesystem Watcher** — `@parcel/watcher` with platform backends. Gitignore-aware. (`packages/core/src/filesystem/watcher.ts`)
-
-## Top Adoptable Ideas for savant-code
-
-| Priority | Feature | Why |
-|----------|---------|-----|
-| HIGH | Four-Axis LLM Route Architecture | Eliminates provider duplication |
-| HIGH | Durable Session Runner | Gold standard for coding agent sessions |
-| HIGH | Session Input Delivery (Steer/Queue) | Sophisticated human-agent interaction |
-| HIGH | System Context Algebra | Advanced memory with source-based composition |
-| HIGH | Session Compaction with Structured Summary | Essential for long-running agents |
-| HIGH | Location-Scoped Service Graph | Clean multi-project isolation |
-| HIGH | Plugin Hook Surface | Comprehensive extensibility model |
-| MEDIUM | Content-Addressed Snapshots | Safe code modification |
-| MEDIUM | Agent Step Limits with Forced Summary | Simple safety mechanism |
-| MEDIUM | Tool Output Store with Preview | Efficient large output handling |

package/docs/reports/repos/zero.md

@@ -1,123 +0,0 @@
-# Zero — Feature Inventory
-
-> **Repo:** `resources/zero` | **Language:** Go (1.26.5+)
-> **License:** MIT | **Tagline:** "A terminal coding agent you own."
-
-## Overview
-
-Zero is a Go-based terminal coding agent with 25+ LLM providers, OS-level sandboxing (landlock/seccomp/seatbelt), a multi-agent swarm with mailbox-based communication, an execution profile controller (adaptive self-regulation), a completion policy (headless work gating), post-edit LSP verification, and a two-phase memories pipeline. It is one of the most technically complete coding agents.
-
-## Feature Inventory
-
-### Multi-Provider LLM (25+)
-
-- **Provider-Neutral Types** — `CompletionRequest`/`StreamEvent` abstraction with single `Provider.StreamCompletion` interface. OpenAI, Anthropic, Gemini, Groq, OpenRouter, DeepSeek, Mistral, xAI, Qwen, Kimi, Ollama, LM Studio, MiniMax, etc. (`internal/providers/`, `internal/providercatalog/`)
-
-### Agent Loop
-
-- **Core Run** — 3184 lines. Malformed tool call detection, repeated-failure guards, stall retries, empty-turn nudges, max-turn fallback, proactive/reactive compaction. `RequireCompletionSignal` for headless mode. (`internal/agent/loop.go`)
-
-### Context Compaction
-
-- **Proactive + Reactive** — Summarizes oldest middle at ~70% context. Per-provider calibration by usage. Turn-boundary preservation (never splits tool_use/tool_result). Plan/structured state preserved. (`internal/agent/compaction.go`)
-
-### Permission & Sandbox Engine
-
-- **Dual-Layer** — Tool-level permission metadata + sandbox engine evaluating path scope, network, destructive shell, command-prefix grants. Platform backends: macOS seatbelt, Linux landlock/bwrap/seccomp, Windows restricted token + WFP. Risk classification (low/medium/high/critical) with structured `Block` codes. (`internal/sandbox/`)
-
-### Multi-Agent Swarm
-
-- **Mailbox-Based** — Orchestrator spawns/coordinates/collects from concurrent specialists. Per-agent mailboxes, task handoff, channel-based `WaitSettled` (not polling). Deferred tool loading adapts to swarm state. (`internal/swarm/`)
-
-### Specialist Sub-Agents
-
-- **Markdown Manifests** — Three scopes (built-in, user, project). `extends` inheritance. `GenerateSpecialist` tool (agent creates its own sub-agents). Background state survives restarts. (`internal/specialist/`)
-
-### MCP (Client + Server)
-
-- **Bidirectional** — Both client and server. stdio and HTTP transports. OAuth. (`internal/mcp/`)
-
-### Plugin System
-
-- **Directory-with-Manifest** — `plugin.json` with tools, hooks, skills. Auto-registration of skill roots. (`internal/plugins/`)
-
-### Skills System
-
-- **On-Demand Loading** — Multi-root discovery with earlier-root-wins. Registered in system prompt. (`internal/skills/`)
-
-### Hooks System
-
-- **Shell Commands** — stdin-JSON payload (not env vars). `beforeTool` (blocking) / `afterTool` (advisory). Audit trail. (`internal/hooks/`)
-
-### Session Management
-
-- **Resume/Fork/Rewind** — Append-only event log (`events.jsonl` + `metadata.json`). Parent/root IDs for lineage. (`internal/sessions/`)
-
-### Cron Scheduler
-
-- **Built-in Recipes** — `git-recap`, `ci-watch`, `todo-pulse`, `daily-summary`. Customizable loop prompt. DST-aware parser. (`internal/cron/`)
-
-### Self-Correction System
-
-- **Post-Edit Verification** — LSP diagnostics + project verification (tests/lint) fed back to model. Attempt ceiling (default 3). Autonomy-gated (low = report only, high = auto-fix). (`internal/agent/selfcorrect.go`)
-
-### Execution Profile Controller
-
-- **Adaptive Self-Regulation** — Observes per-turn signals (tool failure streak, risky mutations, self-correct failures, uncertain completion) and one-shot escalates loop parameters. Safety: escalation targets are displaced values (can never introduce unauthorized knobs). (`internal/agent/profile_controller.go`)
-
-### Parallel Tool Execution
-
-- **Read-Ahead** — Independent read-only tools (read_file + grep + glob) execute concurrently (up to 8). Resource-key conflict detection prevents same-path parallel reads. (`internal/agent/parallel_tools.go`)
-
-### Deferred Tool Loading
-
-- **State-Dependent** — Many tools withheld, advertised as compact `tool_search` lines. Coordination tools un-defer when swarm exists. (`internal/tools/deferred.go`)
-
-### Stream-JSON Protocol
-
-- **Headless/Automation** — Schema-versioned (v2), line-delimited JSON. Structured events with permission metadata. (`internal/streamjson/`)
-
-### Agent Evals
-
-- **Process-Level Assertions** — Fixtures with expected changed files, forbidden files, verification commands, required trace events. (`internal/agenteval/`)
-
-### Spec Mode
-
-- **Plan-First** — Draft spec, pause for human review, then execute. (`internal/specmode/`)
-
-### Other
-
-- **LSP Integration** — Background async diagnostics. (`internal/lsp/`)
-- **Worktrees** — Isolated git worktrees. (`internal/worktrees/`)
-- **Completion Policy** — Validates headless work is actually complete. (`internal/agent/completion_policy.go`)
-- **GitHub Action** — Composite action with install + run + post. (`action.yml`)
-- **Notification System** — Webhook notifier with redaction. (`internal/notify/`)
-- **Tracing** — Opt-in per-turn timing recorder. (`internal/trace/`)
-- **Performance Benchmarking** — Manifest-based test suites with model matrix. (`internal/perfbench/`)
-- **OAuth Management** — Device code, loopback, PKCE, encrypted storage, keyring, singleflight refresh. (`internal/oauth/`)
-- **Redaction System** — Secret scrubbing at every output boundary. (`internal/redaction/`)
-- **File Tracker** — Staleness detection for external changes. (`internal/tools/file_tracker.go`)
-- **Output Budget** — Category-aware semantic truncation. (`internal/tools/output_budget.go`)
-- **Voice Dictation** — Cloud (Deepgram), local (Whisper), OpenAI Realtime. (`internal/dictation/`)
-- **Image/PDF Input** — File, clipboard, PDF extraction. (`internal/imageinput/`)
-- **Repository Map** — Deterministic, 4 KiB cap. (`internal/repomap/`)
-- **Daemon Mode** — Background worker pool with socket IPC. (`internal/daemon/`)
-- **Escalate Model Tool** — Mid-run switch to stronger model. (`internal/tools/escalate_model.go`)
-- **Response Style** — Concise, explanatory, review, balanced. (`internal/agent/types.go`)
-- **Ask-User Tool** — Structured questions with options, descriptions, recommended defaults. (`internal/tools/ask_user.go`)
-- **Theme System** — 12+ built-in themes. (`internal/tui/theme.go`)
-
-## Top Adoptable Ideas for savant-code
-
-| Priority | Feature | Why |
-|----------|---------|-----|
-| HIGH | Execution Profile Controller | Adaptive self-regulation based on failure signals |
-| HIGH | Completion Policy | Ensures headless work is actually complete |
-| HIGH | Self-Correction System (LSP + test) | Post-edit verification with autonomy gating |
-| HIGH | Multi-Agent Swarm (mailbox-based) | Mature orchestration with task handoff |
-| HIGH | Context Compaction (proactive + reactive) | Essential for long sessions |
-| HIGH | Deferred Tool Loading (state-dependent) | Keeps context lean |
-| HIGH | Agent Evals (process-level assertions) | Tests process, not just output |
-| HIGH | Spec Mode (plan-first with review gate) | High-stakes change safety |
-| MEDIUM | Provider-Neutral Runtime Types | Clean multi-provider abstraction |
-| MEDIUM | Permission & Sandbox Engine | Dual-layer safety with structured block codes |

package/docs/reports/savant-code-benchmark-v2-2026-08-03.md

@@ -1,76 +0,0 @@
-# Savant-Code Benchmark v2 — Run Report (2026-08-03)
-
-> **Generated:** 2026-08-03
-> **Runner:** `evals/v2` harness (`bun run v2/src/cli.ts`)
-> **Tasks:** `savant-v2-error-recovery-001`, `savant-v2-mao-options-001`,
-> `savant-v2-pure-add-001`, `savant-v2-pure-rename-001` (4 total)
-> **Raw artifacts:** `evals/v2/reports/{report.json,report.md}`
-> **FID:** FID-2026-0803-012 (release-readiness audit)
-
-## Baseline mode — 4/4 PASS ✅
-
-`--mode baseline` (offline; applies each task's golden patch and runs the
-deterministic checks — no API key, no model calls):
-
-| Task ID | Category | Difficulty | Status | Duration |
-|---|---|---|---|---|
-| savant-v2-error-recovery-001 | error_recovery | medium | **PASS** | 0.14s |
-| savant-v2-mao-options-001 | multi_agent_orchestration | medium | **PASS** | 0.21s |
-| savant-v2-pure-add-001 | pure_coding | easy | **PASS** | 0.11s |
-| savant-v2-pure-rename-001 | pure_coding | medium | **PASS** | 0.11s |
-
-**Total:** 4 · **Passed:** 4 · **Failed:** 0 · **Errors:** 0 · **Timeouts:** 0
-
-Two task-authoring defects were found and fixed during this run (see below);
-after the fixes, all four tasks pass deterministically.
-
-## Evaluate mode — 0/4 (environmental) ⚠️
-
-`--mode evaluate` (live agent via `SavantCodeClient`, `SAVANT_CODE_API_KEY`
-wired from the local `OPENCODE_GO_API_KEY`, concurrency 1):
-
-| Task ID | Status | Cause |
-|---|---|---|
-| savant-v2-error-recovery-001 | FAIL | Verification failed — `injectFault` is a documented MVP no-op (`v2/src/runners/savant.ts`), so the env-fault task cannot pass by design |
-| savant-v2-mao-options-001 | TIMEOUT | 60s task timeout — free-tier provider rate-limited (OpenRouter → Google AI Studio, HTTP 429 `free-models-per-min`) |
-| savant-v2-pure-add-001 | TIMEOUT | 60s task timeout — same provider rate limiting |
-| savant-v2-pure-rename-001 | TIMEOUT | 60s task timeout — same provider rate limiting |
-
-**Total:** 4 · **Passed:** 0 · **Failed:** 1 · **Timeouts:** 3
-
-The evaluate run **proves the harness end-to-end** (agent registry populated,
-live model calls issued, tool execution, trace capture, report writing), but
-the wired key routes to OpenRouter's free tier, which rate-limits (429) and
-rejects the BYOK provider key (`API_KEY_INVALID` from Google AI Studio). A
-valid Savant backend key is required for a meaningful evaluate pass.
-
-## Defects found & fixed (FID-2026-0803-012)
-
-1. **RR-1 (CRITICAL)** — the 12 benchmark eval fixture JSONs
-   (`eval-{codebuff,manifold,plane,saleor}[-hard|-2].json`) were deleted in
-   the working tree but still tracked in git, breaking `evals/benchmark`.
-   Restored via `git restore`.
-2. **RR-2** — `main.ts` / `main-single-eval.ts` referenced the never-existing
-   `eval-savant-code.json`; retargeted to the real `eval-codebuff.json`.
-3. **RR-5a** — `add-fix` task's golden patch had a stale single-line pre-image
-   for the multi-line `add.js`; regenerated the patch → baseline now 4/4.
-4. **RR-5b** — v2 evaluate mode passed **no `agentDefinitions`**, so every run
-   failed instantly with `Invalid agent ID: "savant". Available agents: `.
-   Wired `loadLocalAgents` through `cli.ts → RunnerConfig →
-   SavantAgentRunner → client.run()` (mirrors `evals/benchmark/run-benchmark.ts`).
-5. **RR-5c** — `writeJsonReport` crashed on cyclic provider error objects
-   (`TypeError: Converting circular structure to JSON`); added a
-   circular-safe replacer that flattens `Error` instances.
-
-## How to re-run
-
-```bash
-# Baseline (offline, no key)
-bun --cwd evals run v2/src/cli.ts --tasks-dir v2/tasks --output-dir v2/reports --mode baseline
-
-# Evaluate (needs a valid SAVANT_CODE_API_KEY)
-SAVANT_CODE_API_KEY=... bun --cwd evals run v2/src/cli.ts --tasks-dir v2/tasks --output-dir v2/reports --mode evaluate --concurrency 1
-```
-
-**Next step:** re-run evaluate with a valid Savant backend key once available;
-track the new report in this file.

package/docs/savant-code-modes.md

@@ -1,338 +0,0 @@
-# Savant-Code Modes — Historical Feature Writeup (2026-07-20)
-
-> **⚠️ HISTORICAL — Do not use this document as current product or architecture guidance.** This diagnostic audit
-> describes the pre-rebrand mode system and intentionally preserves obsolete paths, model names, and provider options as
-> an audit record. Current agent definitions and provider behavior are documented in `README.md`, `ARCHITECTURE.md`,
-> `agents/savant/savant.ts`, and `sdk/src/impl/model-provider.ts`. No pending implementation plan is tracked by this file.
-
-## TL;DR — answer to "do modes do anything?"
-
-Yes — but only half of the wire. The input-box **DEFAULT/LITE/MAX/PLaN** toggle is *partly* real:
-
-| Half of the wire | Status post-rebrand |
-|---|---|
-| **Agent ID load** (`AGENT_MODE_TO_ID[mode]`) | **Live** — each mode loads a distinct `AgentDefinition` with different model default, `providerOptions`, tool list, validation, and system prompt. |
-| **`costMode` value** (`AGENT_MODE_TO_COST_MODE[mode]`) | **Dead** — was meant for the now-defunct SavantCode backend. Flows through `sdk/run.ts` as a string, but no backend consumes it on the OpenRouter-direct path. |
-
-If you only have time to read one paragraph: the toggle changes *which agent runs*; it does **not** change billing,
-rate limiting, telemetry, or session gating — those were backend responsibilities that no longer exist.
-
----
-
-## 1. Two concepts that the prior searches conflated
-
-There is a frequent source of confusion because the word "mode" appears in three different idioms in this codebase:
-
-| Concept | Where defined | What it controls |
-|---|---|---|
-| `AgentMode` (`'DEFAULT' \| 'LITE' \| 'MAX' \| 'PLAN'`) | `cli/src/utils/constants.ts` | Which `AgentDefinition` loads + the `costMode` label forwarded to the SDK |
-| `InputMode` (`'default' \| 'bash' \| 'homeDir' \| 'plan' \| 'review' \| 'interview' \| 'usage' \| 'image' \| 'help' \| 'connect:chatgpt' \| 'outOfCredits' \| 'subscriptionLimit'`) | `cli/src/utils/input-modes.ts` | Input-box prefix/slash-command context. Determines whether the AgentMode toggle is visible. |
-| `costMode` (`'free' \| 'lite' \| 'normal' \| 'max' \| 'experimental' \| 'ask'`) | `common/src/constants/model-config.ts` | Legacy billing tag, passed to SDK. Same names as AgentMode labels but a separate string union. |
-
-The input-box toggle the user sees in `DEFAULT/LITE/MAX` is the **AgentMode toggle** from the first table. The
-`costMode` it maps to is from the third table — and is dead on the OpenRouter-direct path.
-
----
-
-## 2. Full wire path (verbatim)
-
-```text
-┌─────────────────────────────────────────────────────────────────────────┐
-│  cli/src/utils/constants.ts                                             │
-│    AGENT_MODE_TO_ID                                                    │
-│      DEFAULT → 'base2'                                                 │
-│      LITE    → IS_SAVANT_FREE ? 'base2-free' : 'base2-lite'             │
-│      MAX     → 'base2-max'                                             │
-│      PLAN    → 'base2-plan'                                            │
-│    AGENT_MODE_TO_COST_MODE                                             │
-│      DEFAULT → 'normal'                                                │
-│      LITE    → IS_SAVANT_FREE ? 'free' : 'lite'                        │
-│      MAX     → 'max'                                                   │
-│      PLAN    → 'normal'                                                │
-└─────────────────────────────────────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│  cli/src/components/agent-mode-toggle.tsx                              │
-│    Compact hover-expandable SegmentedControl.                           │
-│    Renders only if IS_SAVANT_FREE is false (returns null otherwise).    │
-│    Click "DEFAULT" → calls onToggle/onSelectMode.                      │
-│    All UI action handlers funnel through resolveAgentModeClick.         │
-└─────────────────────────────────────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│  cli/src/state/chat-store.ts                                           │
-│    Field: `lastMessageMode: AgentMode`                                 │
-│    Updated by the toggle; read by use-send-message.ts.                  │
-└─────────────────────────────────────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│  cli/src/hooks/use-send-message.ts (~line 632)                          │
-│    Reads `agentMode` from current input, reads `lastMessageMode` from   │
-│    useChatStore. Resolves `agent = AGENT_MODE_TO_ID[mode]` and passes  │
-│    `costMode: AGENT_MODE_TO_COST_MODE[mode]` to createRunConfig.        │
-└─────────────────────────────────────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│  cli/src/utils/create-run-config.ts                                    │
-│    Returns RunConfig object with `agent`, `costMode`, maxAgentSteps:    │
-│    MAX_AGENT_STEPS_DEFAULT, fileFilter (sensitive-file block), etc.    │
-└─────────────────────────────────────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│  sdk/src/run.ts                                                        │
-│    Receives `costMode?: string` in RunOptions.                              │
-│    Forwards to agent-runtime via callMainPrompt call.                   │
-└─────────────────────────────────────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│  agents/base2/{base2,base2-lite,base2-max,base2-plan,base2-fast,       │
-│  base2-free}.ts                                                        │
-│    Loaded agent definition:                                             │
-│    - `model` (default if no override)                                  │
-│    - `providerOptions`                                                 │
-│    - `toolNames` (gated by isFast / noAskUser / noGravityIndex flags)   │
-│    - `systemPrompt` (Savant the {Lite|Max|Plan|Fast|Free} Orchestrator) │
-│    - `displayName`                                                     │
-│    - `instructionsPrompt`, `stepPrompt`, `handleSteps`                 │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-The half of the wire that is **dead post-rebrand**: `costMode` and `agentDefinions`. The `costMode` parameter still
-flows but no backend reads it. The `agentDefinions` (legacy backend-loaded agent registry) is unused.
-
----
-
-## 3. What each mode ACTUALLY produces (per working-tree evidence)
-
-Read from `agents/base2/base2.ts` and the wrappers `agents/base2/base2-{lite,max,plan,fast,free}.ts`. Each row is
-the difference the runtime sees when you click the toggle in the input box.
-
-| AgentMode | Loaded agent ID | `model` (default if no override) | `providerOptions` | Validation | Tools (vs base2) |
-|---|---|---|---|---|---|
-| `DEFAULT` | `base2` | `'anthropic/claude-opus-4.8'` | `{ only: ['amazon-bedrock'] }` | strict | full |
-| `MAX` | `base2-max` | same as DEFAULT | `{ only: ['amazon-bedrock'] }` | strict + "keep working until satisfied" | full |
-| `LITE` (SavantCode, IS_SAVANT_FREE=false) | `base2-lite` | `'minimax/minimax-m3'` (OpenRouter label) | `{ only: ['amazon-bedrock'] }` | strict | full |
-| `LITE` (SavantFree, IS_SAVANT_FREE=true) | `base2-free` | `'minimax/minimax-m3'` (OpenRouter label) | `{ data_collection: 'deny' }` | strict | full |
-| `PLAN` | `base2-plan` *(via `createBase2('default', { planOnly: true })`)* | `'anthropic/claude-opus-4.8'` | `{ only: ['amazon-bedrock'] }` | plan-only override (no write tools at runtime) | full |
-| (used inside `noAskUser: true` shell) | `base2-fast-no-validation` | whatever model override is passed | `{ only: ['amazon-bedrock'] }` | `hasNoValidation: true` | drops `write_todos`, `suggest_followups`, `ask_user` |
-
-Notes:
-
-- The model strings are OpenRouter routing labels, not endpoints. `minimax/minimax-m3` and
-  `anthropic/claude-opus-4.8` both reach OpenRouter's unified `/api/v1/chat/completions` endpoint; OpenRouter
-  handles the underlying provider.
-- `base2-free` and `base2-lite` route to the same `minimax/minimax-m3` model but differ in `providerOptions` — free
-  mode denies data collection, lite mode restricts to bedrock (which is questionable on OpenRouter-direct, see §7).
-- `modelOverride ?? ...` — if you pick a model in the model picker UI, that override wins over the AgentMode
-  default. The picker choice is honoured regardless of mode.
-- `'free'` and `'lite'` AgentMode IDs differ but produce nearly identical AgentDefinitions; the only behavioral
-  delta is the `providerOptions`.
-
----
-
-## 4. The agent-mode-toggle UI component (`cli/src/components/agent-mode-toggle.tsx`)
-
-- Compact, hover-expandable segmented control. Returns `null` if `IS_SAVANT_FREE === true`.
-- Internal `useHoverToggle()` hook manages open/close with `OPEN_DELAY_MS=0`, `CLOSE_DELAY_MS=250`,
-  `REOPEN_SUPPRESS_MS=250` to prevent flicker on rapid hover transitions.
-- Builds segments from `AGENT_MODES` (the array derived from `Object.keys(AGENT_MODE_TO_ID)`).
-  - Each non-active mode renders as a clickable segment.
-  - Active mode renders as a `> MODE` indicator.
-- Click handlers funnel through the exported `resolveAgentModeClick(currentMode, clickedId, hasOnSelectMode)` helper:
-  - Clicking an active mode → `{ type: 'closeActive' }`
-  - Clicking a different mode → `{ type: 'selectMode'; mode: target }` if `onSelectMode` is provided, otherwise `{
-    type: 'toggleMode'; mode: target }`.
-- Disabled when `inputFocused === false` (the toggle won't open if the terminal is not focused — UX rule).
-
-### Visibility rule (which `InputMode`s expose the toggle)
-
-From `cli/src/utils/input-modes.ts`, each `InputModeConfig` has `showAgentModeToggle`:
-
-| InputMode | Toggle visible? |
-|---|---|
-| `default`, `homeDir`, `usage`, `help` | ✅ |
-| `bash`, `plan`, `review`, `interview`, `image`, `connect:chatgpt`, `outOfCredits`, `subscriptionLimit` | ❌ |
-
-Plus an unconditional override: in SavantFree builds, all toggle visibility is forced off.
-
-Practical consequence: when the user types `/plan`, `/review`, or `/interview`, the agent-mode toggle disappears.
-When the user is back in the default chat, it reappears. `subscriptionLimit` and `outOfCredits` also hide it
-because there's no interactive mode toggle to display.
-
----
-
-## 5. The `costMode` dead path
-
-`costMode` is declared in `common/src/constants/model-config.ts`:
-
-```typescript
-export const costModes = [
-  'free', 'lite', 'normal', 'max', 'experimental', 'ask',
-] as const
-export type CostMode = (typeof costModes)[number]
-```
-
-It flows through the wire as a string label:
-
-1. `AGENT_MODE_TO_COST_MODE[mode]` in `constants.ts` produces one of `'free' | 'lite' | 'normal' | 'max' |
-   'experimental' | 'ask'`.
-2. `use-send-message.ts` passes it to `createRunConfig({ costMode, ... })`.
-3. `create-run-config.ts` puts it in the returned RunConfig object.
-4. `sdk/src/run.ts` declares it on `RunOptions` and forwards it to `callMainPrompt(...)` in `agent-runtime`.
-5. `agent-runtime` checks `isFreeMode(costMode)` to gate ChatGPT-OAuth-direct flows in
-   `sdk/src/impl/model-provider.ts` and `gemini-with-fallbacks.ts`.
-
-**The only runtime effect of `costMode` today** is the `isFreeMode(costMode)` check — which only matters if the
-user is using a ChatGPT OAuth direct connection (out-of-scope post-rebrand since OpenRouter is the universal
-backend). On the OpenRouter-direct path, **`costMode` is fully inert** — the value flows through but nothing reads
-it.
-
-If you keep `costMode` in the wire purely as a labeling facility (or for backward compatibility with hypothetical
-future metering), that's fine. If you want to drop it entirely, the chain is short.
-
----
-
-## 6. Files to touch for redesign (full table)
-
-| File | What to change |
-|---|---|
-| `cli/src/utils/constants.ts` | Replace `AGENT_MODE_TO_ID` + `AGENT_MODE_TO_COST_MODE` tables. New modes, new IDs, new cost-mode mapping. Optionally drop `AGENT_MODE_TO_COST_MODE` entirely. |
-| `cli/src/components/agent-mode-toggle.tsx` | Rename mode labels, update `buildExpandedSegments` and `resolveAgentModeClick` exports to recognize new mode strings. May rename `AgentMode` type itself. |
-| `cli/src/utils/input-modes.ts` | Decide whether the toggle should appear in additional `InputMode`s. Flip `showAgentModeToggle: true` for any new contexts (e.g. `/fast` slash command). |
-| `cli/src/utils/create-run-config.ts` | `CreateRunConfigParams.costMode` field — drop or repurpose. Remove from `costMode` line in the returned object. |
-| `cli/src/hooks/use-send-message.ts` (around line 632) | Update `AGENT_MODE_TO_COST_MODE[mode]` lookup site. If costMode is dead, simplify to drop the field. |
-| `agents/base2/{base2,base2-lite,base2-max,base2-plan,base2-fast,base2-free}.ts` | If the new mode names map to distinct agent IDs, edit the wrapper files. `agents/base2/base2.ts` `createBase2(mode, options?)` is the universal seam — most logic lives here. |
-| `common/src/constants/model-config.ts` | `costModes` const array; shrink or rename if you change the union. |
-| `sdk/src/run.ts` (~line 150) | `costMode: costMode ?? 'normal'` — drop or rename the field on `RunOptions`. The SDK has no enforcement, so the field is purely a wire label. |
-| `agents/browser-use/browser-use.test.ts` (sav-26-040 reference) | Other tests/snapshots need a sweep if you rename the `AgentDefinition` IDs. |
-
----
-
-## 7. ⚠️ Latent risk: `amazon-bedrock` is still hardcoded in non-free modes
-
-`agents/base2/base2.ts` has:
-
-```typescript
-const defaultProviderOptions = isFree
-  ? { data_collection: 'deny' as const }
-  : { only: ['amazon-bedrock'] }
-```
-
-This forces every DEFAULT/MAX/LITE/PLAN run to **only** route through amazon-bedrock. If your OpenRouter-direct
-setup no longer includes amazon-bedrock as a routing surface (likely, since you replaced the old SavantCode backend
-with a master-key OpenRouter path), this would silently **fail every paid-mode request** at the AI SDK layer.
-
-Verify before redesign ships:
-
-```bash
-cd /c/Users/spenc/dev/savant-code
-grep -rn 'amazon-bedrock' agents/ common/ sdk/ packages/ 2>/dev/null | grep -v __tests__
-```
-
-If amazon-bedrock appears anywhere outside test mocks and ECHO docs, decide whether to:
-
-- (a) Drop the `only: ['amazon-bedrock']` constraint entirely — neutral request, OpenRouter picks the cheapest route.
-- (b) Repoint to whatever provider you actually use (e.g. `anthropic-direct`, `minimax-direct`).
-- (c) Document Bedrock as still-approved for paid runs and confirm contract.
-
-This is **not** an aesthetic issue — it's a runtime correctness issue. Catching this in the redesign pass is
-cheaper than discovering it after shipping.
-
----
-
-## 8. Three redesign options (in smallest-to-largest blast radius)
-
-### Option A — Strip `costMode` only. Keep mode toggle + AgentDefinition IDs.
-
-- Remove `costMode` from `cli/src/utils/create-run-config.ts` (line ~92), `sdk/src/run.ts` (~line 150),
-  `cli/src/hooks/use-send-message.ts` (~line 632).
-- Keep `AGENT_MODE_TO_ID`, keep `base2-lite/base2-max/etc.` files.
-- ~30 lines removed across 3 files. No UX change.
-- *When to pick this:* if you want the cheapest possible cleanup and the toggle feature is acceptable as-is.
-
-### Option B — Rename modes to match new product language.
-
-- Replace mode label table in `cli/src/utils/constants.ts` (`DEFAULT → STANDARD`, `LITE → FAST`, `MAX → PRO`, drop
-  or rename `PLAN`).
-- Update strings in `agent-mode-toggle.tsx` (the `buildExpandedSegments` function constructs segments from
-  `AGENT_MODES` automatically — only hardcoded labels are the `> MODE` indicator).
-- Optionally rename the underlying `AgentDefinition` IDs (`base2-lite → base2-fast`, etc.).
-- ~50 lines changed across 3–5 files. UX-visible change (button labels in input box).
-- *When to pick this:* if the current label names don't reflect the product's new positioning.
-
-### Option C — Collapse the toggle. Always load one agent.
-
-- Set `AGENT_MODE_TO_ID = { DEFAULT: 'base2', LITE: 'base2', MAX: 'base2', PLAN: 'base2' }` (or just remove the
-  mode toggle entirely).
-- The picker becomes purely cosmetic; `costMode` is irrelevant.
-- ~10 lines changed plus 1 component deletion.
-- *When to pick this:* if you've decided one prompt pipeline + one model picker is enough and you want maximum
-  simplicity.
-
-There's no Option D / "do nothing" — the latent `amazon-bedrock` risk in §7 alone warrants touching this code.
-
----
-
-## 9. Verification steps before making changes
-
-Run these to confirm the wire path:
-
-1. Boot the CLI: `cd /c/Users/spenc/dev/savant-code && bun dev`.
-2. Add a one-line debug log at `cli/src/components/agent-mode-toggle.tsx` `handleSegmentClick`, e.g.
-   `console.log('[modes] click', mode, '→', agent)`.
-3. Add a debug log at `cli/src/hooks/use-send-message.ts` near line 632: `console.log('[modes] sending', { agent,
-   costMode, modelOverride })`.
-4. Click each mode (DEFAULT/LITE/MAX/PLaN), send a one-line prompt, and confirm:
-   - Agent ID is what `AGENT_MODE_TO_ID[mode]` says.
-   - `costMode` reaches `create-run-config.ts` and is forwarded.
-5. Pick a model from the model picker UI that overrides the AgentMode default; confirm `modelOverride` wins.
-6. Run `grep -rn 'amazon-bedrock' agents/ common/ sdk/ packages/ 2>/dev/null` to confirm any Bedrock leftover is
-   intentional.
-
----
-
-## 10. Decisions checklist (when you rename `base2` later)
-
-Before touching any file, capture decisions on:
-
-- [ ] New mode names (default + alternative flavor list)
-- [ ] Whether to keep AgentDefinition-per-mode load (Option B/C) or centralize to a single agent (Option A)
-- [ ] Whether `costMode` survives as a deprecated field or is fully stripped
-- [ ] Whether `providerOptions.only: ['amazon-bedrock']` is still valid in the OpenRouter-direct setup
-- [ ] Which **`InputMode`** contexts should still expose the toggle
-- [ ] What to do with `base2-free` and `base2-lite` (which produce near-identical AgentDefinitions)
-- [ ] Whether `planOnly` becomes a real `AgentMode` or stays as a `createBase2` flag
-- [ ] FIDs/documentation updates: open FID-2026-0720-031 at the start of work, file CHANGELOG.md entry + migrate
-  FID to `archive/` at close
-
----
-
-## 11. Related documents
-
-- [`ARCHITECTURE.md`](../ARCHITECTURE.md) — 9-agent roster (Orchestrator, Detective, Forge, Verifier, Recorder,
-  Thinker, Scout, Researcher, Scribe)
-- [`ECHO.md`](../ECHO.md) — Perfection Loop FSM, FID lifecycle
-- [`docs/agents-and-tools.md`](agents-and-tools.md) — Agent roster breakdown
-- [`docs/SAVANT-VERSIONING.md`](SAVANT-VERSIONING.md) — Versioning convention
-- [`CHANGELOG.md`](../CHANGELOG.md) — FID-2026-0719-030 entry documents the agent-runtime `__tests__/` exclusion
-  decision that touches overlapping infrastructure
-
-Pending FIDs this writeup will fold into:
-
-- FID-2026-0720-031 (to be opened): Modes feature redesign after base2 rename
-
----
-
-*Audit performed 2026-07-20. Working-tree evidence: 8 files read directly (`agents/base2/base2.ts`,
-`agents/base2/base2-lite.ts`, `agents/base2/base2-max.ts`, `agents/base2/base2-free.ts`,
-`agents/base2/base2-plan.ts`, `agents/base2/base2-fast.ts`, `common/src/constants/model-config.ts`,
-`sdk/src/impl/model-provider.ts`, `cli/src/components/agent-mode-toggle.tsx`, `cli/src/utils/input-modes.ts`,
-`cli/src/utils/constants.ts`, `cli/src/utils/create-run-config.ts`). Conclusions: costMode path is dead
-post-rebrand; AgentMode toggle wire path is real but partially cosmetic; amazon-bedrock constraint is a latent
-runtime risk.*