savant-code 0.0.17 → 0.0.19

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

@@ -0,0 +1,78 @@
+# 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

@@ -0,0 +1,123 @@
+# 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

@@ -0,0 +1,76 @@
+# 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

@@ -0,0 +1,338 @@
+# 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.*