loki-mode 8.6.0 → 8.8.0

package/mcp/__init__.py

@@ -75,4 +75,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '8.6.0'
+__version__ = '8.8.0'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "8.6.0",
+  "version": "8.8.0",
   "description": "Loki Mode by Autonomi. Autonomous spec-to-product system: takes a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief to a deployed app via the RARV-C closure loop with 8 quality gates. Provider-agnostic (Claude Code, OpenAI Codex, Cline, Aider).",
   "keywords": [
     "agent",

package/plugins/loki-mode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "loki-mode",
   "displayName": "Loki Mode",
-  "version": "8.6.0",
+  "version": "8.8.0",
   "description": "Autonomous spec-to-product build system with a built-in trust layer (RARV-C closure loop, 8 quality gates, completion council). Ships Loki's spec-hardening, drift-detection, and deterministic PR verification commands plus the Loki MCP server.",
   "author": {
     "name": "Autonomi",

package/providers/aider.sh

@@ -58,12 +58,18 @@ _aider_default_from_catalog() {
     if [ -f "${script_dir}/models.sh" ]; then
         # shellcheck source=./models.sh
         source "${script_dir}/models.sh"
-        loki_latest_model aider development 2>/dev/null || echo "claude-opus-4-8"
+        loki_latest_model aider development 2>/dev/null || echo "openrouter/deepseek/deepseek-v3.2"
     else
-        echo "claude-opus-4-8"
+        echo "openrouter/deepseek/deepseek-v3.2"
     fi
 }
-AIDER_DEFAULT_MODEL="${LOKI_AIDER_MODEL:-${LOKI_MODEL_DEVELOPMENT:-$(_aider_default_from_catalog)}}"
+# Resolution: provider-scoped env > catalog. The GLOBAL tier var
+# (LOKI_MODEL_DEVELOPMENT) is deliberately NOT in this chain: aider takes
+# litellm full model strings ("openrouter/deepseek/deepseek-v3.2"), while the
+# global tier var carries Claude CLI aliases ("sonnet"), so a global set for
+# one provider silently produced `aider --model sonnet`. Namespace-incompatible,
+# not merely mis-ordered. Do not re-add it.
+AIDER_DEFAULT_MODEL="${LOKI_AIDER_MODEL:-$(_aider_default_from_catalog)}"
 PROVIDER_MODEL_PLANNING="$AIDER_DEFAULT_MODEL"
 PROVIDER_MODEL_DEVELOPMENT="$AIDER_DEFAULT_MODEL"
 PROVIDER_MODEL_FAST="$AIDER_DEFAULT_MODEL"
@@ -134,6 +140,32 @@ resolve_model_for_tier() {
     echo "$AIDER_DEFAULT_MODEL"
 }
 
+# provider_invoke_argv <tier> <prompt> -- see providers/claude.sh for the full
+# rationale. Populates _LOKI_INVOKE_ARGV so a caller can wrap it in `timeout`,
+# which cannot exec a shell function.
+#
+# Unlike Codex, provider_get_tier_param here returns a real MODEL NAME, so it is
+# safe to pass to --model. An empty value omits the flag rather than sending
+# `--model ""`, which aider rejects.
+provider_invoke_argv() {
+    local tier="${1:-development}"
+    local prompt="${2:-}"
+    local model
+    model="$(provider_get_tier_param "$tier" 2>/dev/null || printf '%s' "")"
+    _LOKI_INVOKE_ARGV=(aider --yes-always --no-auto-commits)
+    [ -n "$model" ] && _LOKI_INVOKE_ARGV+=(--model "$model")
+    # LOKI_AIDER_FLAGS is a documented operator knob (CLI --aider-flags) that
+    # provider_invoke honours. Dropping it here would make the timeout-safe path
+    # silently ignore operator config that the normal path applies. Deliberately
+    # word-split, matching provider_invoke's unquoted $extra_flags expansion.
+    if [ -n "${LOKI_AIDER_FLAGS:-}" ]; then
+        # shellcheck disable=SC2206
+        _LOKI_INVOKE_ARGV+=(${LOKI_AIDER_FLAGS})
+    fi
+    # Aider takes the prompt via --message, not positionally.
+    _LOKI_INVOKE_ARGV+=(--message "$prompt")
+}
+
 # Tier-aware invocation
 # Aider uses a single model configured externally, tier has no effect
 provider_invoke_with_tier() {

package/providers/claude.sh

@@ -381,7 +381,18 @@ provider_invoke_argv() {
     local prompt="${2:-}"
     _loki_build_claude_auto_flags "$tier" "${LOKI_COMPLEXITY:-standard}" ""
     local model
-    model="$(loki_tier_route_model "$tier" 2>/dev/null || provider_get_tier_param "$tier")"
+    # Use the SAME resolver as the non-argv path. This previously called
+    # loki_tier_route_model with one argument, but that function takes TWO
+    # (tier, model) and echoes its second arg when routing is off -- so it
+    # returned an EMPTY string with rc=0, the `||` fallback never fired, and
+    # every argv-based claude invocation shipped with no --model flag at all.
+    #
+    # Do NOT "fix" this by chaining provider_get_tier_param + loki_tier_route_model
+    # here: that reproduces base+route but SKIPS loki_apply_max_tier_clamp, so
+    # LOKI_MAX_TIER=sonnet still emitted `--model opus` and the cost ceiling was
+    # silently unenforced on exactly the timeout-safe seam. resolve_model_for_tier
+    # is base -> route -> clamp -> alt-provider in one call; keep both paths on it.
+    model="$(resolve_model_for_tier "$tier" 2>/dev/null || provider_get_tier_param "$tier")"
     _LOKI_INVOKE_ARGV=(
         claude --dangerously-skip-permissions
         "${_LOKI_CLAUDE_AUTO_FLAGS[@]+"${_LOKI_CLAUDE_AUTO_FLAGS[@]}"}"

package/providers/cline.sh

@@ -59,12 +59,18 @@ _cline_default_from_catalog() {
     if [ -f "${script_dir}/models.sh" ]; then
         # shellcheck source=./models.sh
         source "${script_dir}/models.sh"
-        loki_latest_model cline development 2>/dev/null || echo "claude-opus-4-8"
+        loki_latest_model cline development 2>/dev/null || echo "openrouter/deepseek/deepseek-v3.2"
     else
-        echo "claude-opus-4-8"
+        echo "openrouter/deepseek/deepseek-v3.2"
     fi
 }
-CLINE_DEFAULT_MODEL="${LOKI_CLINE_MODEL:-${LOKI_MODEL_DEVELOPMENT:-$(_cline_default_from_catalog)}}"
+# Resolution: provider-scoped env > catalog. The GLOBAL tier var
+# (LOKI_MODEL_DEVELOPMENT) is deliberately NOT in this chain: cline takes
+# full routed model strings ("openrouter/deepseek/deepseek-v3.2"), while the
+# global tier var carries Claude CLI aliases ("sonnet"), so a global set for
+# one provider silently changed cline's model too. Namespace-incompatible,
+# not merely mis-ordered. Do not re-add it.
+CLINE_DEFAULT_MODEL="${LOKI_CLINE_MODEL:-$(_cline_default_from_catalog)}"
 PROVIDER_MODEL_PLANNING="$CLINE_DEFAULT_MODEL"
 PROVIDER_MODEL_DEVELOPMENT="$CLINE_DEFAULT_MODEL"
 PROVIDER_MODEL_FAST="$CLINE_DEFAULT_MODEL"
@@ -132,6 +138,23 @@ resolve_model_for_tier() {
     echo "$CLINE_DEFAULT_MODEL"
 }
 
+# provider_invoke_argv <tier> <prompt> -- see providers/claude.sh for the full
+# rationale. Populates _LOKI_INVOKE_ARGV so a caller can wrap it in `timeout`,
+# which cannot exec a shell function.
+#
+# Unlike Codex, provider_get_tier_param here returns a real MODEL NAME, so it is
+# safe to pass to -m. An empty value omits the flag rather than sending `-m ""`,
+# matching provider_invoke's existing model_args guard.
+provider_invoke_argv() {
+    local tier="${1:-development}"
+    local prompt="${2:-}"
+    local model
+    model="$(provider_get_tier_param "$tier" 2>/dev/null || printf '%s' "")"
+    _LOKI_INVOKE_ARGV=(cline -y)
+    [ -n "$model" ] && _LOKI_INVOKE_ARGV+=(-m "$model")
+    _LOKI_INVOKE_ARGV+=("$prompt")
+}
+
 # Tier-aware invocation
 # Cline uses a single model configured externally, tier has no effect
 provider_invoke_with_tier() {

package/providers/model_catalog.json

@@ -1,12 +1,13 @@
 {
   "_comment": "Canonical model catalog. Update this single file when a provider ships a new model. Providers/web-app/docs read from here.",
+  "_source_of_truth": "models[] is authoritative. Each entry's `tier` decides what that tier resolves to, first match wins, so order within models[] is load-bearing. The top-level latest_<tier> keys are DERIVED mirrors kept only for existing readers (dashboard/server.py, tools/probe-model-catalog.py, tests); never hand-edit them out of step with models[] -- tests/test-model-catalog-single-source.sh fails when they disagree. A provider whose models[] has no entry for a tier must declare `tier_fallback` saying which tier substitutes; there is no implicit fallback.",
   "schema_version": 1,
   "updated": "2026-07-29",
   "providers": {
     "claude": {
       "latest_planning": "claude-opus-4-8",
       "latest_development": "claude-sonnet-5",
-      "latest_fast": "claude-sonnet-5",
+      "latest_fast": "claude-haiku-4-5",
       "cli_aliases": {
         "fable": "claude-fable-5",
         "opus": "claude-opus-4-8",
@@ -51,6 +52,10 @@
       "latest_planning": "gpt-5.3-codex",
       "latest_development": "gpt-5.3-codex",
       "latest_fast": "gpt-5.3-codex",
+      "tier_fallback": {
+        "development": "planning",
+        "fast": "planning"
+      },
       "models": [
         {
           "id": "gpt-5.3-codex",
@@ -58,14 +63,16 @@
         },
         {
           "id": "o3",
-          "tier": "planning"
+          "tier": "planning",
+          "notes": "Alternative planning model. NOT the default -- gpt-5.3-codex is listed first and first match wins."
         },
         {
           "id": "o4-mini",
-          "tier": "fast"
+          "tier": "legacy",
+          "notes": "Was tier=fast, which made the cheap tier resolve to o4-mini while latest_fast said gpt-5.3-codex. Codex does not differentiate tiers by model, so it is not any tier's default; parked at tier=legacy so it stays discoverable without being dispatched."
         }
       ],
-      "notes": "Codex uses a single model with effort level (xhigh/high/low) for tier differentiation"
+      "notes": "Codex uses a single model with effort level (xhigh/high/low) for tier differentiation, so development and fast declare an explicit tier_fallback to planning rather than naming separate models."
     },
     "cline": {
       "latest_planning": "openrouter/deepseek/deepseek-v3.2",
@@ -164,10 +171,14 @@
       ]
     },
     "generic": {
-      "_comment": "Fallback for ANY provider not named above (bring-your-own endpoint). All three tiers collapse to one open model, the same shape codex uses. Override per tier with LOKI_<PROVIDER>_MODEL_<TIER> or wholesale with LOKI_<PROVIDER>_MODEL.",
+      "_comment": "Fallback for ANY provider not named above (bring-your-own endpoint). All three tiers collapse to one open model, the same shape codex uses, declared via tier_fallback. Override per tier with LOKI_<PROVIDER>_MODEL_<TIER> or wholesale with LOKI_<PROVIDER>_MODEL.",
       "latest_planning": "openrouter/deepseek/deepseek-v3.2",
       "latest_development": "openrouter/deepseek/deepseek-v3.2",
-      "latest_fast": "openrouter/deepseek/deepseek-chat",
+      "latest_fast": "openrouter/deepseek/deepseek-v3.2",
+      "tier_fallback": {
+        "planning": "development",
+        "fast": "development"
+      },
       "models": [
         {
           "id": "openrouter/deepseek/deepseek-v3.2",

package/providers/models.sh

@@ -16,12 +16,40 @@
 _LOKI_MODELS_SH_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
 LOKI_MODEL_CATALOG="${LOKI_MODEL_CATALOG:-$_LOKI_MODELS_SH_DIR/model_catalog.json}"
 
+# GENERIC CAPABILITY TIERS. Callers should ask for small|medium|high and never
+# name a vendor model. medium is the DEFAULT.
+#
+#   small  -> the cheap/fast model   (claude: haiku, codex: luna)
+#   medium -> the workhorse          (claude: sonnet, codex: terra)  [default]
+#   high   -> the expensive/best     (claude: opus,   codex: sol)
+#
+# WHY AN ALIAS LAYER RATHER THAN A RENAME: the catalog already keys models by
+# planning/development/fast and several call sites depend on those names. This
+# maps onto them instead of duplicating the mapping, so there is exactly one
+# place a model id is written down. Hardcoding "medium = claude-sonnet-5"
+# anywhere would recreate the drift class this repo keeps paying for -- a doc
+# that named a default matching neither the code nor the catalog, and a test
+# that demanded open-weights providers resolve to a Claude model.
+loki_tier_alias() {
+    case "${1:-medium}" in
+        small|fast)              printf 'fast' ;;
+        high|planning|best)      printf 'planning' ;;
+        medium|development|'')   printf 'development' ;;
+        # Unknown value falls back to the DEFAULT rather than failing the run:
+        # a typo in a pipeline config should not change which model you pay for
+        # silently, and it should not halt a build either. The caller can see
+        # what resolved via loki_latest_model.
+        *)                       printf 'development' ;;
+    esac
+}
+
 # Return the "latest_<tier>" id for a provider from the catalog.
 # Args: $1 provider (claude|codex|cline|aider)
-#       $2 tier     (planning|development|fast)
+#       $2 tier     (planning|development|fast, or small|medium|high)
 loki_latest_model() {
     local provider="${1:-claude}"
-    local tier="${2:-planning}"
+    local tier
+    tier="$(loki_tier_alias "${2:-planning}")"
     local tier_upper
     tier_upper=$(printf '%s' "$tier" | tr '[:lower:]' '[:upper:]')
     local provider_upper
@@ -74,7 +102,34 @@ if not p:
     p = providers.get("generic")
     if not p:
         sys.exit(1)
-model = p.get(f"latest_{tier}")
+
+# SINGLE SOURCE OF TRUTH: models[] is authoritative, top-level latest_<tier> is
+# derived. Before this, both existed independently and drifted -- claude
+# latest_fast said claude-sonnet-5 while models[tier=fast] said claude-haiku-4-5,
+# so asking for the cheap tier silently billed the mid tier. models[] wins
+# because it is the richer structure (context_window, max_output, open_weights,
+# alias, notes per model); the top-level keys carry nothing it does not.
+#
+# ORDER IS LOAD-BEARING: a provider may declare several models at one tier
+# (codex lists gpt-5.3-codex and o3 both as planning). First match wins, so the
+# FIRST entry at a tier is the default. Reordering models[] changes what real
+# builds dispatch. tests/test-model-catalog-single-source.sh pins this.
+models = [m for m in p.get("models", []) if isinstance(m, dict)]
+model = next((m.get("id") for m in models if m.get("tier") == tier), None)
+
+if not model:
+    # No entry at this tier. Falling back must be DECLARED, never accidental:
+    # codex genuinely runs one model for every tier and varies reasoning effort
+    # instead, so an absent tier is legitimate for it -- but silently walking to
+    # some other tier is how you end up dispatching a model nobody chose. The
+    # provider states the substitution in the catalog as tier_fallback, and we
+    # honor only that.
+    fallback_tier = (p.get("tier_fallback") or {}).get(tier)
+    if fallback_tier:
+        model = next(
+            (m.get("id") for m in models if m.get("tier") == fallback_tier), None
+        )
+
 if not model:
     sys.exit(1)
 print(model)

package/providers/opencode.sh

@@ -67,14 +67,20 @@ PROVIDER_DEGRADED=false
 PROVIDER_MAX_OUTPUT_TOKENS=128000
 
 # Model defaults. opencode names models "provider/model"; the catalog supplies
-# the value and the standard LOKI_<PROVIDER>_MODEL_<TIER> chain overrides it.
+# the value and LOKI_OPENCODE_MODEL overrides it.
 _opencode_default_from_catalog() {
     if type loki_latest_model >/dev/null 2>&1; then
         loki_latest_model opencode development 2>/dev/null && return 0
     fi
     printf 'openrouter/deepseek/deepseek-v3.2'
 }
-OPENCODE_DEFAULT_MODEL="${LOKI_OPENCODE_MODEL:-${LOKI_MODEL_DEVELOPMENT:-$(_opencode_default_from_catalog)}}"
+# Resolution: provider-scoped env > catalog. The GLOBAL tier var
+# (LOKI_MODEL_DEVELOPMENT) is deliberately NOT in this chain: opencode takes
+# "provider/model" strings ("openrouter/deepseek/deepseek-v3.2"), while the
+# global tier var carries Claude CLI aliases ("sonnet"), so a global set for
+# one provider silently changed opencode's model too. Namespace-incompatible,
+# not merely mis-ordered. Do not re-add it.
+OPENCODE_DEFAULT_MODEL="${LOKI_OPENCODE_MODEL:-$(_opencode_default_from_catalog)}"
 PROVIDER_MODEL_PLANNING="$OPENCODE_DEFAULT_MODEL"
 PROVIDER_MODEL_DEVELOPMENT="$OPENCODE_DEFAULT_MODEL"
 PROVIDER_MODEL_FAST="$OPENCODE_DEFAULT_MODEL"

package/references/multi-provider.md

@@ -71,6 +71,15 @@ PROVIDER_CONTEXT_WINDOW=1000000 # Max context tokens (Opus 4.7: 1M at standard p
 PROVIDER_MAX_OUTPUT_TOKENS=128000
 ```
 
+`PROVIDER_CONTEXT_WINDOW` also caps code-review size. The review diff and prompt
+limits derive from it (assuming ~3 bytes per token and ~75% of the window for
+input), so a small-window local model is not handed a prompt sized for a 200k
+one. The derived value is only ever used to LOWER a cap, and a window at or above
+roughly 188889 tokens clamps to the historical 400000/425000 byte defaults, so no
+provider shipping today changes behavior (a provider that declares no window
+keeps the defaults as well). `LOKI_REVIEW_MAX_DIFF_BYTES` and
+`LOKI_REVIEW_MAX_PROMPT_BYTES` still override both.
+
 #### Degraded Mode
 ```bash
 PROVIDER_DEGRADED=false        # true for Codex/Aider

package/skills/providers.md

@@ -73,6 +73,40 @@ Quality gates, the completion council, and the Evidence Receipt are all
 model-agnostic: they assert on the artifact that was built, not on which model
 built it. A cheaper or local model gets the same verification as Opus.
 
+### Keeping the model catalog current
+
+`providers/model_catalog.json` is hand-maintained and carries an `updated` date.
+Models ship constantly, so the catalog rots. `loki doctor` reports its age in a
+`Model catalog:` section and warns once it passes 90 days:
+
+```
+WARN  Last updated 2026-01-02 (210 days ago) -- may be missing newer models
+      Refresh: python3 tools/probe-model-catalog.py
+```
+
+The warning is **advisory only**. It never changes an exit code and never fails
+a build (`tests/test-model-catalog-staleness.sh` asserts exactly that). It also
+makes no network call: doctor reads the local file's `updated` field and nothing
+else, so air-gapped operation (`docs/air-gapped.md`) is unaffected.
+
+To refresh:
+
+```bash
+python3 tools/probe-model-catalog.py     # report new model IDs found in provider docs
+```
+
+The probe reads public provider documentation and reports model IDs that are not
+yet in the catalog. **It never rewrites the catalog.** You edit
+`providers/model_catalog.json` by hand -- bump the relevant `latest_<tier>` and
+add the model to `models[]` -- then set `updated` to today. Model adoption is a
+human decision: cost, capability, and behavioural changes all need a person to
+weigh them, and a model ID that does not exist would break every run that
+selects it. Being stale is recoverable; a fabricated model ID is not.
+
+The probe is also wired to a weekly CI job (`.github/workflows/model-catalog-probe.yml`)
+that opens a draft PR with its findings. That job is CI-only -- it is not on any
+runtime path.
+
 ## Claude Code (Default, Full Features)
 
 **Best for:** All use cases. Full autonomous capability.
@@ -246,7 +280,7 @@ aider --message "$prompt" --yes-always --no-auto-commits --model model_name
 **Environment Variables:**
 | Variable | Description |
 |----------|-------------|
-| `LOKI_AIDER_MODEL` | Model to use (default: claude-3.7-sonnet) |
+| `LOKI_AIDER_MODEL` | Model to use. Default comes from `providers/model_catalog.json` (`aider.latest_development`), not a hardcoded string. The global `LOKI_MODEL_*` tier vars do NOT apply to aider. |
 | `LOKI_AIDER_FLAGS` | Extra aider flags (e.g., --architect) |
 
 ---