claude-autorouter 0.3.7 → 0.5.0

package/.env.example

@@ -1,7 +1,8 @@
 # Copy to .env and load with: node --env-file=.env bin/autorouter.mjs claude
 AUTOROUTER_AUTH_MODE=subscription
 AUTOROUTER_CLIENT_PROFILE=compatible
-# Jev remains the default evaluator. Ollama is experimental; see settings below.
+# Local Ollama is the default evaluator (experimental; see settings below).
+# Set jev to use TypeSafe's hosted evaluator, which needs TYPESAFE_API_KEY.
 AUTOROUTER_EVALUATOR=jev
 # The launcher enables the router status line for this session. Set 0 to keep your own.
 AUTOROUTER_STATUSLINE=1
@@ -12,10 +13,12 @@ AUTOROUTER_STATUSLINE=1
 # AUTOROUTER_CLIENT_PROFILE=auto
 # Optional metadata logs on stderr. Redirect stderr to a file when using the UI.
 # AUTOROUTER_DEBUG=1
-# Optional persistent JSONL decision logs, one file per session per launch.
+# Optional persistent JSONL decisions/outcomes, one file per session per launch.
 # Includes up to 500 characters of user prompt text; keep the directory local.
 # Unset or empty disables logging. This does not print prompts in the terminal.
 # AUTOROUTER_SESSION_LOG_DIR=/absolute/path/to/autorouter-sessions
+# Omit all prompt excerpt fields (does not enable logging by itself).
+# AUTOROUTER_SESSION_LOG_MODE=metadata
 # Optional: allow two tool-free Stop-hook continuations, then end the turn on
 # the third block. Applies to /goal and all Stop/SubagentStop hooks.
 # Unset keeps Claude's default (currently 8); 0 DISABLES the cap.
@@ -40,7 +43,7 @@ AUTOROUTER_MIN_CONFIDENCE=0.75
 # Experimental local evaluator in AutoRouter 0.3.2+: native decision API only.
 # Install/start Ollama 0.35+, then run:
 # claude-autorouter setup --evaluator ollama --pull --force
-# Defaults to nimble:9b-q4_K_M (~5.63 GB download); --force replaces user config.
+# Defaults to nimble:9b-q4_K_M (~5.63 GB download); --force preserves other settings.
 # Existing downloads are kept. Replace Qwen config/environment values from 0.2.0.
 # All local models use /v1/systemone; custom tags/aliases must support that API.
 # Add --ollama-model LOCAL_TAG_OR_ALIAS to setup to choose another suitable model.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of conduct
+
+Be respectful and constructive in issues, pull requests, reviews and other project spaces. Welcome people with different backgrounds and experience levels, focus criticism on ideas and code, and respect requests to stop unwanted interaction.
+
+Harassment, discriminatory or demeaning remarks, sexualized conduct, threats, personal attacks, and publishing someone's private information without consent are not acceptable. The same expectations apply when representing the project outside its repository.
+
+Report concerns privately to maintainer Fabio Rapposelli at [fabio@rapposelli.org](mailto:fabio@rapposelli.org), with the subject `AutoRouter conduct report`. Include relevant links and enough context to investigate; avoid publishing the report or unrelated private information. Reports will be handled with discretion, sharing information only as needed to investigate and respond.
+
+The maintainer may request changes, remove content, issue warnings, or temporarily or permanently restrict participation according to the severity and pattern of behavior. Requests to review a decision can be sent to the same address. This policy is maintained on a best-effort basis and does not promise a response deadline.

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to AutoRouter
+
+Bug reports, documentation improvements, reproducible routing cases and focused fixes are welcome. Read the [support guide](SUPPORT.md) before opening an issue, and use the [private security reporting process](SECURITY.md) for vulnerabilities. Participation follows the [code of conduct](CODE_OF_CONDUCT.md).
+
+For a substantial behavior change, open an issue describing the problem and proposed scope before implementing it. Fabio Rapposelli ([@frapposelli](https://github.com/frapposelli)) maintains the project and reviews design and release decisions. Review is best effort; there is no guaranteed response time.
+
+Coding agents working in a source checkout should follow [AGENTS.md](https://github.com/frapposelli/claude-autorouter/blob/main/AGENTS.md). [CLAUDE.md](https://github.com/frapposelli/claude-autorouter/blob/main/CLAUDE.md) imports the same guidance for Claude Code.
+
+## Submit a change
+
+Fork the repository, clone your fork and create a branch. While the repository is private, this requires access and permission to fork; existing collaborators can use a branch in their authorized checkout.
+
+```sh
+git clone https://github.com/YOUR-USERNAME/claude-autorouter.git
+cd claude-autorouter
+git switch -c describe-your-change
+```
+
+Use Node.js 22+ and macOS or Linux (including WSL). Install pinned development tools, then run the local checks:
+
+```sh
+npm ci --ignore-scripts --no-audit --no-fund
+npm run check
+npm test
+npm run test:package
+```
+
+Tests use synthetic local services and credentials. They require loopback binding, but make no paid provider calls, downloads or user-config changes. The package check installs and exercises the exact distributable archive. Opt-in provider/model canaries are described in [development and validation](docs/development.md).
+
+Open a pull request against `main`. Describe the problem, resulting behavior and relevant validation, linking an issue when one exists. Keep the change focused, include meaningful regressions for behavior changes, and update affected help or documentation. Report any checks you could not run. Real provider calls and model downloads are not required for ordinary contributions; label their results separately if deliberately run.
+
+Use synthetic fixtures. Do not commit credentials, personal configuration, private prompts, transcripts or session logs. Metadata-only logs can still contain identifying information; inspect any material before sharing it. Contributions are accepted under the project's [Apache-2.0 license](LICENSE); submit only work you have the right to contribute. No CLA or sign-off workflow is required.
+
+## Changing behavior
+
+Follow the [request lifecycle](docs/development.md#request-lifecycle-and-model-continuity). Keep authentication and permission decisions owned by Claude. Preserve provider bytes, signed history and unfamiliar extensions. Routing must check compatibility in every profile; new human tasks remain eligible to switch models. Active task state is separate from disposable classification caches, and only clean, successfully forwarded completion evidence can establish confirmed continuation state.
+
+Update `src/contracts.mjs` alongside configuration, decision or telemetry changes. Keep the normalizer allowlist and privacy tests aligned. Logged selections are not successful outcomes, logging stays opt-in, and metadata mode must omit prompts. [Static/style checks](docs/development.md#static-contracts-and-style) run in CI; do not add runtime dependencies for developer tooling.
+
+## Model and pricing updates
+
+1. Identify the exact provider model ID; a family keyword or custom alias is not capability evidence.
+2. Update `src/model-catalog.mjs` with the authoritative source and review date. Verify context/output limits, thinking, tool choice, native tool features and Auto eligibility.
+3. Add valid-source compatibility fixtures for every affected profile and a regression for the new restriction or permitted switch. Keep unknown models/extensions conservative.
+4. Update thinking adaptation only where documented; token counting and inference must apply the same compatibility policy.
+5. If rates change, review `src/savings.mjs`, bump its pricing version/date and source, and test cache TTL/modifier/unknown-model coverage. Never silently price old logs using an unrecorded new table.
+6. Run all three local checks and exact-package fixtures. Report separately any explicitly invoked real-provider observations and their limits.
+
+## Evaluation and performance
+
+Declare label agreement, acceptable tiers and under-routing thresholds before testing a candidate. Preserve fixture checksums and held-out cases; transport, evaluator availability, policy and task quality are separate gates. Profile coverage requires all three tiers for compatible routing and Sonnet/Opus for Auto.
+
+Capture a baseline before changing overhead. Repeat the same workload and hardware with the [router/storage harnesses](docs/development.md#performance-regression-measurements), retaining call counts, latency distributions, memory and background load. Numerical timing gates are local and opt-in; CI checks deterministic cancellation/resource behavior. Real local-model benchmarks need representative memory sizes and observed cold/warm conditions.
+
+## Releasing
+
+Use the [release procedure](docs/releasing.md) and retain the tested immutable archive. Acceptance by npm and public availability are separate states. Verify registry integrity and an isolated install before calling a release verified. A pending submission is investigated or verified again, rather than blindly republished. New CLI interfaces and event-schema changes should be reviewed together as a minor release; correctness-only fixes can be independent patches.

package/README.md

@@ -1,126 +1,103 @@
-# Claude AutoRouter
+# AutoRouter
 
-Use Haiku, Sonnet, and Opus in one Claude Code session. A local gateway classifies coding requests with the selected evaluator, applies compatibility and context checks, and streams the selected model's response back to Claude Code. Claude's internal permission classifiers retain their selected model; execution requests keep their server safety-review settings and verdicts when routed. [TypeSafe Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev) is the default; an experimental Ollama backend evaluates requests locally.
+An independent local model-routing gateway for Claude Code. AutoRouter is not affiliated with, endorsed by, or sponsored by Anthropic. The existing npm package and command remain `claude-autorouter`.
 
-Requires Node.js 22+, macOS or Linux (including WSL), an installed `claude` command, and a Claude subscription login or Anthropic API key. The default evaluator also requires a [TypeSafe API key](https://console.typesafe.ai). There are no runtime package dependencies. Native Windows is not supported in this release.
+Use Haiku, Sonnet and Opus in one Claude Code session. AutoRouter evaluates each coding request, checks model compatibility and context capacity, and forwards it through a local gateway. Native Ollama `/v1/systemone` models are the default, experimental local evaluator, so task excerpts stay on your machine; [TypeSafe Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev) is an optional hosted evaluator (`setup --evaluator jev`). Claude owns authentication, tool permissions and safety review.
 
-## Install and start
-
-Install from [npm](https://www.npmjs.com/package/claude-autorouter):
+Requires Node.js 22+, macOS or Linux (including WSL), an installed `claude` command, and a Claude subscription login or Anthropic API key. The default evaluator also needs a [TypeSafe API key](https://console.typesafe.ai). The installed CLI has no runtime dependencies.
 
-```sh
-npm install -g claude-autorouter
-```
+Version 0.4.0 adds `config`, `sessions` and `doctor --evaluate-local`, durable task continuity, and clearer model outcomes. Upgrade from 0.3.x to use these commands. The [contributor guide](CONTRIBUTING.md) explains local verification, and the [release guide](docs/releasing.md) covers the changes and verified publication.
 
-Set up once, then launch from any project directory:
+## Install and start
 
 ```sh
+npm install -g claude-autorouter
 claude-autorouter setup
 claude-autorouter doctor
 cd /path/to/project
 claude-autorouter claude
 ```
 
-Setup defaults to your Claude subscription and prompts for your Jev key without echoing it. If Claude is not already signed in, run `claude auth login`. No Anthropic API key or exported subscription token is needed for subscription mode. Jev has separate credentials and billing.
+Setup defaults to your Claude subscription and the local Ollama evaluator (Ollama 0.35+ with the default model; add `--pull` to download it), so it asks for no evaluator key. To use hosted Jev instead, run `claude-autorouter setup --evaluator jev`, which prompts privately for its key. Run `claude auth login` if needed. Jev has separate credentials and billing; subscription mode needs no Anthropic API key. For API billing, use `setup --auth-mode api-key`.
 
-Setup saves a private JSON config at `~/.config/claude-autorouter/config.json`; `XDG_CONFIG_HOME` and `AUTOROUTER_CONFIG` can change its location. Environment variables override saved configuration. Project `.env` files are not loaded automatically.
+AutoRouter launches your installed, unmodified official Claude Code executable. Each user supplies their own login or API credentials. Subscription forwarding is a technical integration, not a claim of provider approval; review the [integration boundaries and current provider-policy notes](docs/subscription-integration.md) for your deployment.
 
-Claude Code arguments pass through:
+Configuration is saved privately at `~/.config/claude-autorouter/config.json`. On macOS, new setups keep keys in the login Keychain; for an existing plaintext configuration, run `claude-autorouter config set AUTOROUTER_SECRET_STORE keychain` to move them. Environment variables override it; project `.env` files are not loaded automatically. `setup --force` updates an existing configuration while preserving other settings. Use focused commands for later edits:
 
 ```sh
-claude-autorouter claude -p "Fix the typo in README.md"
-claude-autorouter --help
-claude-autorouter --version
+claude-autorouter config show
+claude-autorouter config set AUTOROUTER_JEV_TIMEOUT_MS 2000
+claude-autorouter config unset AUTOROUTER_JEV_TIMEOUT_MS
+claude-autorouter help config
 ```
 
-For API billing, use `claude-autorouter setup --auth-mode api-key`. Use `--force` to replace an existing config. Automation can supply `TYPESAFE_API_KEY` and, in API-key mode, `ANTHROPIC_API_KEY` through the environment; keys are never command-line arguments. `doctor` checks local configuration and Claude installation/login state without paid requests. See the [configuration reference](docs/reference.md#configuration).
+Secret updates use a hidden prompt or `--stdin`, never a command-line value. Claude arguments pass through, including `claude-autorouter claude --help`. [Configuration reference](docs/reference.md#configuration).
 
-To use automatic Sonnet/Opus routing with Claude's Auto permission mode (AutoRouter 0.3.7+):
+## Auto permission mode
 
 ```sh
 claude-autorouter claude --permission-mode auto
 ```
 
-This selects the Auto profile, defaulting to Sonnet 5.5 and Opus 5.5. The evaluator can choose again for each new human task, while a task's tool calls and goal continuations retain its selected model. A Haiku verdict uses Sonnet. Native safety review stays enabled; organization policies still apply. Use `AUTOROUTER_CLIENT_PROFILE=auto` for sessions where you select Auto in Claude's UI or saved settings. Version 0.3.6 enabled Auto permissions but passed server-reviewed execution through without routing; version 0.3.7 removes that restriction for compatible requests. [Auto-mode support and limitations](docs/reference.md#auto-permission-mode).
+This profile automatically switches between Sonnet 5.5 and Opus 5.5 for new human tasks. A Haiku verdict uses Sonnet. Tool and `/goal` continuations retain the task's execution model; a new task can switch up or down. Claude's native safety review and organization policies still apply. For Auto selected through Claude's UI, save `AUTOROUTER_CLIENT_PROFILE=auto` with `config set`. [Auto support and limitations](docs/reference.md#auto-permission-mode).
 
-## What you see
+## Inspect decisions
 
-The launcher adds a temporary status line and leaves saved Claude Code settings unchanged:
+The launcher adds a temporary status line, preserving saved Claude settings:
 
 ```text
-● AutoRouter · last Haiku 4.5 · ready · Jev 210ms · est saved $0.04 (75%) vs Opus
-● AutoRouter · Sonnet 5 selected · connecting · Jev→Haiku 290ms · large context
+● AutoRouter · Opus 5.5 · ready · Jev 210ms
+● AutoRouter · Sonnet 5.5 selected · Auto floor from Haiku · Jev 220ms
 ```
 
-The confirmed model comes from Anthropic's response. Claude's own model label can still show its Haiku starting model. `API ctx` measures input against the actual model's known window; a different client limit remains visible as `CLI ctx`.
+`selected` means Anthropic has not reported the serving model yet. Guard reasons and errors stay visible before optional savings. Claude's own model label may show its starting model. [Status details](docs/reference.md#status-line-and-savings).
 
-For a separate decision log per session (optional, disabled by default; AutoRouter 0.3.6+):
+Persistent history is optional and disabled by default. Enable metadata-only records without prompt excerpts:
 
 ```sh
-env AUTOROUTER_SESSION_LOG_DIR="$HOME/.local/state/claude-autorouter/sessions" \
-  claude-autorouter claude
+claude-autorouter config set AUTOROUTER_SESSION_LOG_MODE metadata
+claude-autorouter config set AUTOROUTER_SESSION_LOG_DIR "$HOME/.local/state/claude-autorouter/sessions"
+claude-autorouter claude
+claude-autorouter sessions list
+claude-autorouter sessions show ID --json
 ```
 
-Each JSONL record includes a bounded prompt excerpt, selected model, decision latency, and routing reason. Files persist after Claude exits; terminal output stays quiet. [Session logs](docs/reference.md#session-decision-logs).
-
-Savings are an **API-equivalent estimate for the same token counts**, using Opus as the baseline. They do not measure subscription bill reductions or quota credits and exclude Jev and local compute costs. [Status line and savings details](docs/reference.md#status-line-and-savings).
-
-## Experimental local evaluator
-
-The local setup below requires AutoRouter 0.3.2 or newer. It uses Ollama's native `/v1/systemone` decision API with `nimble:9b-q4_K_M` by default. Jev remains the default evaluator. If upgrading from 0.2.0, replace the old Qwen model configuration using the [migration steps](docs/reference.md#migrating-an-older-ollama-config).
+Copy an `id` from `list`. History separates model decisions from outcomes and reports latency, fallbacks, failures and savings coverage. Choose `prompts` mode for bounded human-task excerpts. Files persist locally; no automatic deletion occurs. [History and privacy](docs/reference.md#session-decision-logs).
 
-Version 0.3.2 excludes Claude's executor system instructions from the local classifier excerpt, retaining task and conversation excerpts. Runtime deadlines default to 1,500 ms for Tev1 0.8B/custom models, 15,000 ms for official Tev1 4B tags, and 30,000 ms for official Nimble tags. Explicit timeout settings, including a `1500` saved with 0.3.1, still override these defaults. Jev is unchanged.
+Savings are **API-equivalent estimates using the recorded Opus baseline and token counts**. They do not measure subscription bill reductions or quota credits, and exclude evaluator and local compute costs. Missing or unsupported usage stays unpriced.
 
-Set `0` to disable AutoRouter's runtime evaluator deadline for one launch using your existing configuration:
+## Local Ollama evaluator
 
-```sh
-AUTOROUTER_OLLAMA_TIMEOUT_MS=0 claude-autorouter claude
-```
-
-To save that setting for an installed Tev1 4B model:
+Ollama is the default evaluator. Start Ollama 0.35+ with a model supporting its native decision endpoint, then choose a model:
 
 ```sh
-claude-autorouter setup --evaluator ollama --ollama-model tev1:4b --ollama-timeout-ms 0 --force
+claude-autorouter setup --evaluator ollama --ollama-model tev1:4b-q4_K_M --pull --force
+claude-autorouter doctor --evaluate-local
+claude-autorouter claude
 ```
 
-The setup flag overrides the timeout environment value and saves it. Cancellation and disconnected clients still stop evaluation, normal errors still use fallback, and startup priming keeps its separate 60-second deadline.
+`--pull` authorizes downloading the chosen model if missing. Setup keeps existing models and settings; ordinary launches download nothing. The default local model is `nimble:9b-q4_K_M`; `tev1:0.8b` is smaller and requires checking its accuracy on your tasks. Local classification needs no Jev key; Jev remains available with `setup --evaluator jev`. Claude still answers through Anthropic. [Model choices, deadlines and historical measurements](docs/reference.md#ollama-evaluator).
 
-Install and start Ollama 0.35 or newer; [version 0.35.0](https://github.com/ollama/ollama/releases/tag/v0.35.0) is a prerelease as of September 29, 2026. Then run:
+To allow a slower local model to finish without AutoRouter's runtime deadline:
 
 ```sh
-claude-autorouter setup --evaluator ollama --pull --force
-claude-autorouter doctor
-claude-autorouter claude
+claude-autorouter config set AUTOROUTER_OLLAMA_TIMEOUT_MS 0
 ```
 
-`--force` replaces existing AutoRouter configuration. `--pull` downloads the selected model only if missing. Setup does not install or start Ollama, or delete existing models. Select a native decision model explicitly with `--ollama-model`:
+Cancellation and response-size limits still apply. The local diagnostic uses synthetic prompts and reports observed latency, classification and fallback reasons; it makes no Anthropic/Jev calls or downloads and preserves unrelated resident models.
 
-| Model | Approximate download | Selection |
-| --- | ---: | --- |
-| [Nimble 9B Q4_K_M](https://ollama.com/library/nimble) | 5.63 GB | Default: `nimble:9b-q4_K_M` |
-| [Tev1 0.8B Q8](https://ollama.com/library/tev1) | 812 MB | `tev1:0.8b` |
-| [Tev1 4B Q4_K_M](https://ollama.com/library/tev1) | 2.7 GB | `tev1:4b-q4_K_M` |
+## Troubleshoot and upgrade
 
-For example, select Tev1 0.8B with:
+Inspect `config show` for environment overrides, and `doctor` for setup health. A valid evaluator verdict can be overridden by continuity, context or model compatibility. `Ollama fallback: timeout` means evaluation failed to finish, rather than predicting Sonnet. Status errors and saved history explain these paths.
 
 ```sh
-claude-autorouter setup --evaluator ollama --ollama-model tev1:0.8b --pull --force
+npm install -g claude-autorouter@latest
+claude-autorouter --version
+claude-autorouter doctor
 ```
 
-Use `--ollama-model tev1:4b-q4_K_M` for the listed 4B variant; `tev1:latest` and `tev1:4b` select the larger Q8 download. Model terms are linked in the listings above; download size does not measure resident memory or routing quality. Custom native model tags and aliases also work.
-
-No Jev key is needed for local classification. The launcher primes the evaluator before opening Claude's UI, and evaluation failures fall back to Sonnet or retain Opus without contacting Jev. Claude still answers through Anthropic, with the same routing guards and subscription limits.
-
-Setup, doctor, and startup show the effective model and deadline. Warmup and doctor do not certify classification speed or accuracy. `Ollama fallback: timeout` means no valid decision arrived in time; it is different from the evaluator choosing Sonnet. Source users can run the [local routing regression](docs/development.md#local-routing-regression) to check all three tiers without Claude or Jev calls.
-
-Historical measurements before 0.3.2, on a 16 GiB M4: Tev1 0.8B matched 18/24 held-out labels with 450 ms median latency and no timeouts at 1,500 ms, including full-excerpt checks. Tev1 4B matched 22/24 with a 10-second diagnostic deadline and 3.15-second median latency. Nimble matched 23/24 with a 30-second deadline and 11.4-second median latency. Both larger models exceeded the then-default 1,500 ms. A separate six-case regression with the 0.3.2 fixes passed for both tested Tev1 4B variants and Nimble; Tev1 0.8B matched only three cases. These small tests do not establish general accuracy or Jev parity. See the [measurements and limits](docs/ollama-evaluation.md) and [Ollama reference](docs/reference.md#ollama-evaluator).
-
-## Behavior and data
+Historical integration observations cover Claude Code 2.1.284–2.1.285. The versioned synthetic protocol fixtures test reviewed request/response contracts; they do not certify the current checkout against a live Claude version. Real-provider checks remain explicitly invoked. [Troubleshooting](docs/reference.md#troubleshooting) covers context use, blocked goals and logging. Run ordinary `claude` to bypass routing.
 
-- The default client profile permits all three routing tiers. Tool continuations, thinking history, model-specific features, and context size can keep or upgrade a model even when the evaluator chooses a cheaper tier. [Routing policy](docs/reference.md#routing-policy).
-- The selected evaluator receives bounded excerpts that can contain source code and tool results: TypeSafe with Jev, or the local service with Ollama. Jev also receives system-text excerpts; the local path excludes Claude's executor system instructions. Anthropic receives the complete request. Images, document payloads, and private thinking are omitted from classifier input. [Data flow and authentication](docs/reference.md#data-flow-and-authentication).
-- Subscription access and usage limits still apply. Model switches can reduce cache reuse; cheaper token prices do not guarantee cheaper completed tasks. Run ordinary `claude` to bypass routing.
-- The launcher is quiet by default. Use `AUTOROUTER_DEBUG=1` for metadata diagnostics or `AUTOROUTER_STATUSLINE=0` to retain your existing status line. [Troubleshooting](docs/reference.md#troubleshooting).
-- For blocked `/goal` loops, optionally launch with `env CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=2 claude-autorouter claude`. Claude then ends the turn on the third consecutive blocking verdict without tool use, leaving the goal unmet. This also affects other Stop/SubagentStop hooks; defaults are unchanged. [Scope and saved configuration](docs/reference.md#shorter-stop-hook-loops-opt-in).
+The evaluator receives bounded task/history excerpts that may contain code and tool results: TypeSafe for Jev, or your loopback Ollama service. Recognizable credentials and personal identifiers are redacted from those excerpts first. Anthropic receives the complete request. Model switching can reduce cache reuse. [Data flow and authentication](docs/reference.md#data-flow-and-authentication).
 
-[Reference](docs/reference.md) · [Development and validation](docs/development.md) · [CI and npm release setup](docs/releasing.md) · [Apache-2.0 license](LICENSE)
+[Reference](docs/reference.md) · [Integration and provider policy](docs/subscription-integration.md) · [Contributing](CONTRIBUTING.md) · [Development](docs/development.md) · [Releases](docs/releasing.md) · [Apache-2.0](LICENSE)

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security policy
+
+## Report privately
+
+Use GitHub's private [Report a vulnerability](https://github.com/frapposelli/claude-autorouter/security/advisories/new) form. Private vulnerability reporting is enabled for this repository. If the form is unavailable, email maintainer Fabio Rapposelli at [fabio@rapposelli.org](mailto:fabio@rapposelli.org) with the subject `AutoRouter security report`.
+
+Do not open a public issue or pull request with exploit details, credentials or sensitive request data. Include the affected AutoRouter and Claude Code versions, operating system, evaluator/client profile, expected security boundary, observed impact and a minimal synthetic reproduction where possible. Do not include real API keys, OAuth tokens, private source code, prompts or transcripts. The maintainer can coordinate any additional evidence privately.
+
+Reports are handled on a best-effort basis; there is no guaranteed response time or bounty program. We will coordinate investigation, remediation and disclosure with the reporter before publishing details.
+
+## Supported versions and scope
+
+Security fixes target the latest stable release. Older releases are not maintained as separate security branches; users may need to upgrade. Reports against `main` are also welcome.
+
+Relevant reports include credential exposure, unauthorized access to the local gateway or saved configuration, unintended disclosure through logs, and routing or request changes that weaken Claude's authentication or permission boundaries. Provider accounts, billing and vulnerabilities in Claude Code, TypeSafe or Ollama should also be reported to the responsible provider when applicable.
+
+## Handling diagnostic data
+
+AutoRouter's default evaluator is local Ollama, which keeps classification on loopback. The optional hosted Jev evaluator (`--evaluator jev`) receives bounded task/history excerpts, which may contain private code or tool results. Recognizable credentials and personal identifiers are redacted from those excerpts first; this pattern-based filter reduces, but does not eliminate, disclosure. Anthropic still receives the full inference request. See [data flow and authentication](docs/reference.md#data-flow-and-authentication).
+
+New macOS setups keep saved keys in the login Keychain. Existing and non-macOS configurations keep plaintext keys in the private configuration file until you run `claude-autorouter config set AUTOROUTER_SECRET_STORE keychain` (macOS only). See [credential storage](docs/reference.md#credential-storage).
+
+Session logging is optional. Enabling only a log directory uses the default `prompts` mode, which includes bounded human-task excerpts with recognizable credentials and personal identifiers redacted (pattern-based, so not exhaustive). Select `AUTOROUTER_SESSION_LOG_MODE=metadata` before enabling a directory to omit those excerpts. Inspect even metadata-only output before sharing it; identifiers, paths or environment details can still be sensitive. Saved logs have no automatic deletion policy. See [history and privacy](docs/reference.md#session-decision-logs).

package/SUPPORT.md

@@ -0,0 +1,18 @@
+# Support
+
+AutoRouter is an independent, community-maintained project. It does not provide official support for Anthropic, TypeSafe or Ollama, and has no response-time guarantee.
+
+For setup and usage, start with the [README](README.md) and [troubleshooting reference](docs/reference.md#troubleshooting). Run `claude-autorouter --version`, `claude --version` and `claude-autorouter doctor` to identify the installation and configuration involved. Ordinary `doctor` performs configuration and local service checks; it does not verify paid-provider access.
+
+Use [GitHub issues](https://github.com/frapposelli/claude-autorouter/issues) for reproducible bugs, feature proposals and questions not answered by the documentation. Repository access is required while the repository is private; if you cannot access it, contact [fabio@rapposelli.org](mailto:fabio@rapposelli.org). For vulnerabilities, follow [SECURITY.md](SECURITY.md) instead of opening an issue. Community conduct reports follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Make a report useful
+
+- Include AutoRouter, Claude Code, Node.js and operating-system versions; include the Ollama version and model tag for local evaluation.
+- Identify the authentication mode, evaluator and client profile without sharing credentials or full environment/configuration dumps.
+- Describe expected and actual behavior, and provide minimal steps using a synthetic prompt or fixture when possible. Distinguish the selected model from the provider-confirmed serving model.
+- Share only the relevant, inspected diagnostic excerpt. Remove secrets, private prompts, responses, source code, personal paths and organization identifiers. Screenshots can disclose this information too.
+
+Logging is disabled by default. When enabling optional session history for a reproduction, explicitly choose `AUTOROUTER_SESSION_LOG_MODE=metadata`; the default `prompts` mode includes task excerpts. Metadata-only output still needs review before sharing. Debug stderr can also contain Claude's own diagnostics. See [session logs](docs/reference.md#session-decision-logs) and [troubleshooting](docs/reference.md#troubleshooting).
+
+Account access, subscription/model eligibility, billing and provider outages belong with the responsible provider. AutoRouter reports can investigate how the gateway handles those failures, but cannot change a provider's account policies. Local-model accuracy and performance depend on the workload and hardware; include those conditions when reporting unexpected classifications.

package/bin/autorouter.mjs

@@ -12,66 +12,48 @@ import { createSessionLog } from '../src/session-log.mjs';
 import { loadUserConfig } from '../src/user-config.mjs';
 import { setup, doctor, ollamaDeadlineText } from '../src/onboarding.mjs';
 import { setupOllama } from '../src/ollama-setup.mjs';
+import { helpText } from '../src/cli-help.mjs';
+import { configCommand } from '../src/config-command.mjs';
+import { sessionsCommand } from '../src/session-history.mjs';
 
 const [command = 'help', ...args] = process.argv.slice(2);
 if (['--version', '-v', 'version'].includes(command)) {
   console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
 } else if (['help', '--help', '-h'].includes(command)
-  || (['setup', 'doctor', 'serve'].includes(command) && args.some(arg => ['--help', '-h'].includes(arg)))) {
-  console.log(`Claude AutoRouter — routing for Haiku, Sonnet, and Opus
-
-Usage:
-  claude-autorouter setup [--auth-mode subscription|api-key] [--force]
-    [--client-profile compatible|native|auto]
-    [--evaluator jev|ollama]
-    [--ollama-model MODEL] [--ollama-timeout-ms N] [--pull]
-    [--stop-hook-block-cap N]
-    [--session-log-dir DIR]
-  claude-autorouter doctor
-  claude-autorouter claude [Claude Code arguments]
-  claude-autorouter serve
-  claude-autorouter --version
-
-Setup defaults to subscription authentication and prompts for keys without echoing.
-For noninteractive setup, supply keys through environment variables.
-User config: ~/.config/claude-autorouter/config.json (or XDG_CONFIG_HOME).
-AUTOROUTER_CONFIG selects a different file; environment variables take precedence.
-Project .env files are never loaded automatically.
-
-Jev is the default evaluator and requires TYPESAFE_API_KEY.
-Ollama evaluates locally and requires Ollama 0.35+ with /v1/systemone.
-Use setup --evaluator ollama --pull to detect Ollama and download a missing model.
-The local default is nimble:9b-q4_K_M; --ollama-model selects another compatible model.
-Smaller Tev1 options: --ollama-model tev1:0.8b or --ollama-model tev1:4b-q4_K_M.
-Local routing deadlines: Tev1 0.8B/custom 1500 ms, Tev1 4B 15000 ms, Nimble 30000 ms.
-Setup --ollama-timeout-ms N saves a routing deadline; use 0 to disable it.
-AUTOROUTER_OLLAMA_TIMEOUT_MS also overrides the deadline; 0 disables it.
-Local routing is experimental; see docs/ollama-evaluation.md for measured limits.
-AUTOROUTER_AUTH_MODE=subscription uses your saved Claude Code login.
-Without setup, AUTOROUTER_AUTH_MODE defaults to api-key and also requires ANTHROPIC_API_KEY.
-AUTOROUTER_CLIENT_PROFILE=compatible (default) enables all three routing tiers.
-Use AUTOROUTER_CLIENT_PROFILE=native to retain Claude Code's own model/thinking settings.
-Use AUTOROUTER_CLIENT_PROFILE=auto for Auto permission mode: Sonnet/Opus routing, native thinking.
-Auto defaults to Sonnet 5.5 and Opus 5.5, switching on new human tasks and retaining tool turns.
-An explicit claude --permission-mode auto selects the auto profile for that launch.
-Claude's permission checks and organization policies still apply; Haiku does not support Auto mode.
-Optional CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=N limits consecutive tool-free Stop-hook continuations.
-Use 2 to stop on the third block; applies to /goal and all Stop/SubagentStop hooks.
-Unset preserves Claude's default; 0 disables the cap. Setup --stop-hook-block-cap N saves it.
-Standalone serve also requires AUTOROUTER_TOKEN (at least 16 characters).
-The claude launcher creates a temporary credential and an ephemeral port.
-It enables an AutoRouter status line for this session (AUTOROUTER_STATUSLINE=0 to opt out).
-Launcher logs are quiet by default; AUTOROUTER_DEBUG=1 enables diagnostic logs on stderr.
-AUTOROUTER_SESSION_LOG_DIR writes private per-session JSONL decision logs with prompt excerpts.
-Unset or empty disables session logs. Setup --session-log-dir DIR saves the directory.
-Jev sends prompt excerpts to TypeSafe; Ollama keeps classification on this machine.
-Complete inference requests still go to Anthropic. See README.md.`);
-} else if (command === 'setup' || command === 'doctor') {
+  || (['setup', 'doctor', 'serve', 'config', 'sessions'].includes(command) && args.some(arg => ['--help', '-h'].includes(arg)))) {
+  console.log(helpText(command === 'help' ? args[0] : command));
+} else if (command === 'claude' && args.length === 1 && ['--help', '-h', '--version', '-v'].includes(args[0])) {
+  // Help/version are Claude-owned commands. No config file, evaluator keys,
+  // gateway, Ollama warmup or temporary status files are needed.
+  const env = { ...process.env };
+  delete env.TYPESAFE_API_KEY;
+  delete env.AUTOROUTER_TOKEN;
+  const child = spawn('claude', args, { stdio: 'inherit', env });
+  child.once('error', () => { console.error('Could not launch Claude Code. Ensure `claude` is installed and on PATH.'); process.exitCode = 1; });
+  child.once('exit', (code, signal) => { process.exitCode = code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1); });
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => child.kill(signal));
+} else if (['setup', 'doctor', 'config', 'sessions'].includes(command)) {
   try {
     if (command === 'setup') await setup(args);
+    else if (command === 'config') {
+      if (await configCommand(args) === false) process.exitCode = 1;
+    }
+    else if (command === 'sessions') {
+      if (await sessionsCommand(args) === false) process.exitCode = 1;
+    }
     else {
-      if (args.length) throw new Error('Usage: claude-autorouter doctor');
-      if (!await doctor()) process.exitCode = 1;
+      const evaluateLocal = args.includes('--evaluate-local');
+      const json = args.includes('--json');
+      if (args.some(arg => !['--evaluate-local', '--json'].includes(arg)) || new Set(args).size !== args.length
+        || (json && !evaluateLocal)) throw new Error('Usage: claude-autorouter doctor [--evaluate-local [--json]]');
+      const controller = new AbortController();
+      const cancel = () => controller.abort();
+      for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, cancel);
+      try {
+        if (!await doctor({ evaluateLocal, json, signal: controller.signal })) process.exitCode = 1;
+      } finally {
+        for (const signal of ['SIGINT', 'SIGTERM']) process.removeListener(signal, cancel);
+      }
     }
   } catch (error) { console.error(error.message); process.exitCode = 1; }
 } else if (!['claude', 'serve'].includes(command)) {
@@ -85,10 +67,9 @@ Complete inference requests still go to Anthropic. See README.md.`);
   const stop = () => {
     if (stopping) return stopping;
     if (server) { server.close(); server.closeAllConnections(); }
-    status?.close();
     // Drain accepted decision records before normal process exit. Pending
     // filesystem writes keep Node alive; no timer or fire-and-forget buffer.
-    stopping = Promise.resolve().then(() => sessionLog?.close()).catch(() => {});
+    stopping = Promise.allSettled([status?.close(), sessionLog?.close()]);
     return stopping;
   };
   try {
@@ -120,15 +101,17 @@ Complete inference requests still go to Anthropic. See README.md.`);
     let claudeArgs = args;
     if (statusEnabled) {
       status = createStatusState({ baselineModel: config.models.opus });
+      await status.ready;
       if (status.path) {
         try { claudeArgs = addStatusLineSettings(args, dirname(status.path)); }
         catch {
-          status.close(); status = undefined;
+          await status.close(); status = undefined;
           console.error('AutoRouter status line unavailable: could not safely prepare session settings. Passing your original settings to Claude.');
         }
       } else console.error('AutoRouter status line unavailable: could not create local status storage.');
     }
     if (config.sessionLogDir) sessionLog = await createSessionLog(config.sessionLogDir, {
+      includePrompts: config.sessionLogMode === 'prompts',
       warn: message => console.error(message),
     });
     // Claude owns the terminal while its UI is running. Status updates use the
@@ -136,7 +119,7 @@ Complete inference requests still go to Anthropic. See README.md.`);
     server = createRouterServer(config, {
       log: diagnosticLogs ? undefined : () => {},
       onStatus: event => status?.update(event),
-      onDecision: sessionLog ? entry => sessionLog.record(entry) : undefined,
+      onRecord: sessionLog ? entry => sessionLog.record(entry) : undefined,
     });
     const address = await listen(server, command === 'claude' ? 0 : config.port);
     const baseUrl = `http://127.0.0.1:${address.port}`;
@@ -155,7 +138,7 @@ Complete inference requests still go to Anthropic. See README.md.`);
       if (status?.path) env.AUTOROUTER_STATUS_FILE = status.path;
       const child = spawn('claude', claudeArgs, { stdio: 'inherit', env });
       child.once('error', () => { console.error('Could not launch Claude Code. Ensure `claude` is installed and on PATH.'); process.exitCode = 1; stop(); });
-      child.once('exit', (code, signal) => { process.exitCode = code ?? (signal === 'SIGINT' ? 130 : 1); stop(); });
+      child.once('exit', (code, signal) => { process.exitCode = code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1); stop(); });
       for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => child.kill(signal));
     }
   } catch (error) {

package/docs/development.md

@@ -1,6 +1,6 @@
 # Development and validation
 
-Use Node.js 22+ from a source checkout on macOS or Linux (including WSL). The project has no runtime package dependencies. Development scripts and tests are separate from the installed CLI; user setup is covered in the [README](../README.md).
+Use Node.js 22+ from a source checkout on macOS or Linux (including WSL). The installed CLI has no runtime package dependencies. Source checks use pinned TypeScript and Node type definitions; install these contributor tools with `npm ci --ignore-scripts --no-audit --no-fund`. Development scripts and tests are separate from the installed CLI; user setup is covered in the [README](../README.md).
 
 ## Local checks
 
@@ -16,6 +16,24 @@ Auto-mode regressions exercise Sonnet → Opus → Opus tool continuation → So
 
 Package validation checks the distributable and installed command rather than relying on the source checkout's paths. Review the [release procedure](releasing.md) before distributing a tarball.
 
+## Request lifecycle and model continuity
+
+The gateway validates the request containers it consumes, evaluates the current task, applies continuity and capacity rules, then checks the proposed target against the shared model catalog. Unknown provider extensions remain intact; when their compatibility with another model is unknown, the source model is retained with a routing reason. Token-count requests apply the same compatibility rules before sending a request.
+
+`src/model-catalog.mjs` contains exact model IDs, capability facts, source links, and a review date. A family name inside a custom alias does not establish capabilities. `src/model-request.mjs` contains explicit thinking adaptations; neither layer strips signed history or permission-review settings. Model updates should change the catalog, include a dated authoritative source, and add a request fixture demonstrating the restriction or new supported switch.
+
+The evaluation cache and active execution state have separate lifetimes. `src/turn-state.mjs` keeps active human tasks and pending tools beyond the evaluator cache TTL. Retired tasks expire, aliases and records are bounded, and exhausting active-state capacity is reported rather than silently evicting another active task. State is process-local; after a gateway restart, missing continuity is reported as unknown until a successful response establishes it again.
+
+The gateway stages a selected model under its request ID. `src/response-observer.mjs` observes serving models, provider fallback boundaries, closed tool calls, usage, and terminal response metadata without altering bytes. A serving-model observation alone is not a successful execution. Only clean completion evidence followed by successful HTTP forwarding commits the continuation model. Cancelled, failed, ambiguous, and superseded attempts cannot overwrite known state. New human tasks remain eligible for upward or downward switching, including Sonnet/Opus in Auto mode.
+
+Direct `Router.route()` embedders that omit `requestId` retain selected, unconfirmed continuity for compatibility. Embedders that execute inference should supply a unique request ID and call `router.complete(id, evidence)` after successful delivery, or `router.complete(id)` on failure. The HTTP gateway owns that lifecycle automatically.
+
+## Evaluation acceptance
+
+Evaluation reports distinguish evaluator availability, rubric agreement, routing policy, tier coverage, transport, and independently checked task completion. An unmeasured gate is explicitly marked unmeasured. Normal runs cannot pass solely on classifier fallback or cached predictions; simulated-outage runs explicitly require fallback. Compatible routing requires all three selected tiers, while Auto requires Sonnet and Opus. Constrained fixtures declare expected guard overrides.
+
+The general and Ollama evaluation scripts accept `--min-agreement` and `--max-under-route-rate`. Their defaults require complete expected-label agreement and no under-routing. Set any alternative thresholds **before** evaluating a candidate, retain the fixture checksum with the report, and keep tuning cases separate from held-out cases. Rubric labels are judgments about synthetic tasks; these reports do not prove end-user task quality or subscription savings. The expanded corpus includes multilingual tasks, short difficult follow-ups, ordinary work in long background context, and task text containing tier-selection instructions. No prompt-policy adjustment should be justified by rerunning and relabeling the held-out set.
+
 ## Run from source
 
 ```sh
@@ -76,7 +94,7 @@ For a classifier-only rubric evaluation:
 npm run eval
 ```
 
-The bundled evaluation makes 12 classifier calls and no Claude generations. Jev is the default and incurs TypeSafe usage; set `AUTOROUTER_EVALUATOR=ollama` to evaluate an installed local model. It reports agreement with the starting rubric, fallback count, and p50/p95 routing latency. Edit `test/fixtures/routing.json` to represent the tasks you want to measure. Rubric agreement alone does not establish answer quality or net savings; compare completed tasks against fixed-model baselines.
+The bundled evaluation makes 19 classifier calls and no Claude generations. Jev is the default and incurs TypeSafe usage; set `AUTOROUTER_EVALUATOR=ollama` to evaluate an installed local model. It reports agreement with the starting rubric, fallback count, and p50/p95 routing latency. Edit `test/fixtures/routing.json` to represent the tasks you want to measure. Rubric agreement alone does not establish answer quality or net savings; compare completed tasks against fixed-model baselines.
 
 For local evaluator measurements, use Ollama 0.35+ and a model compatible with `/v1/systemone`. Distinguish cold model loading from warmed classification, and record the model tag, hardware, Ollama version, context size, prompt length, and resident memory. The launcher primes the classifier with a synthetic task before opening the UI, with a separate deadline of up to 60 seconds. Runtime and benchmark share the 3,000-character/3,000-UTF-8-byte state limit, so include non-ASCII cases and excerpts that fill the budget. Also measure the first request after keep-alive expiration: its reload can hit the normal deadline even when warm requests pass. Repeat on realistic prompt distributions instead of selecting a model from a single easy request. Disk download size is not resident RAM. Keep model downloads opt-in and respect each model's license.
 
@@ -113,3 +131,31 @@ node --env-file=.env scripts/context-probe.mjs --cwd /path/to/synthetic-fixture
 ```
 
 Private repository or connected-tool context may be present even when the typed prompt is harmless. Keep private-payload investigations local unless external processing is authorized. For shareable live regressions, prefer the isolated synthetic fixtures above. The probe report itself persists only metadata.
+
+## Static contracts and style
+
+`npm run check` checks JavaScript syntax, TypeScript/JSDoc contracts for configuration, classifier results, final routing decisions and normalized telemetry, and literal event producers in transport code. `src/contracts.mjs` is the shared development-time type contract; normalizers remain the runtime privacy boundary. Negative fixtures in `test/static-contracts.mts` and `test/static-checks.test.mjs` prove misspelled fields, invalid enums, payload fields and timing strings are rejected before execution. Provider request extensions remain opaque and are validated only where the router consumes them.
+
+Use two-space indentation, LF endings, one final newline, semicolons and single quotes for ordinary strings. Compact pure helpers are allowed when readable; do not reformat unrelated code. The style check rejects trailing whitespace, tab indentation, `var`, and coercing comparisons except deliberate null/undefined checks. TypeScript is a contributor dependency only; public packages keep zero runtime dependencies. CI installs the pinned lockfile before checks and never runs provider inference automatically.
+
+## Versioned protocol evidence
+
+`test/fixtures/claude-protocol-v1.json` is a versioned, newly authored synthetic corpus reviewed against the Messages API, streaming, deferred-tool and fallback contracts. `test/protocol-fixtures.test.mjs` sends it through the real gateway, router and response observer with fake evaluator/upstream services. It covers Auto floors and switches, thinking adaptation and preservation, custom deferred tool references, conservative built-in server-tool history, compaction, scoped goal feedback, parallel agents, model fallback/tool ownership, usage and truncated responses.
+
+Historical Claude Code 2.1.284/2.1.285 report versions, dates and hashes are separate metadata. The corpus does not copy captured prompts, invent provider signatures or certify a live client. Current-source real-provider canaries remain opt-in and unmeasured unless a separate report records them.
+
+## Performance regression measurements
+
+[Router measurements](router-performance.md) and [status-storage measurements](status-performance.md) record the pre-change baseline, repeated candidate runs, hardware/background load and baseline-derived gates. Source-only harnesses use synthetic inputs and providers; no credentials, prompts from user sessions or downloads are involved.
+
+```sh
+node --expose-gc scripts/benchmark-router.mjs baseline /tmp/router-comparison.json
+node --expose-gc scripts/benchmark-router.mjs candidate /tmp/router-comparison.json --check
+node scripts/benchmark-status.mjs --label local-check --check
+```
+
+Identical concurrent classifier inputs share one bounded evaluation. Each request applies its own continuity, capacity and compatibility checks. Cancelling one waiter preserves other waiters; cancelling all releases the shared evaluation. Cache identity retains the complete request, requested model floor, evaluator configuration and rubric hash. New tasks and sequential pinned continuations still evaluate; prior-pin classification reuse was deliberately not enabled. A 64 KiB response limit applies to both evaluators, and local model metadata is limited to 1 MiB. Disabling the Ollama timer does not disable cancellation or these byte limits.
+
+Status writes use one asynchronous writer and a coalesced latest snapshot. Embedders await `state.ready` before using its path, `flush()` when they need persisted evidence, and `close()` before cleanup. Initial storage failures or a one-second readiness timeout disable the optional display. Accepted in-flight writes finish before directory removal, so shutdown cannot recreate files.
+
+The router/storage measurements cover one 16 GiB M4 with synthetic providers. Actual Tev1 4B and Nimble 9B measurements on that Mac and a 64 GiB M2 Ultra are recorded separately in [the hardware comparison](hardware-comparison.md). Both candidates missed the unchanged strict quality gate on both hosts. Model digests and runtime conditions differ, so the cross-host results do not isolate RAM's effect. Use the [transfer bundle instructions](hardware-benchmark.md) to reproduce the workload, recording background load and observed residency. Do not infer model performance from router timings.