@mmerterden/multi-agent-pipeline 20.20.0 → 20.21.0

package/pipeline/lib/route-state.sh

@@ -10,10 +10,11 @@
 # for a configuration the user already gave.
 #
 # Usage:
-#   route-state.sh status                       print the current policy
-#   route-state.sh on  [--strategy=S] [--scope=a,b]
+#   route-state.sh status                       print the current policy and savings
+#   route-state.sh on  [--strategy=S] [--scope=a,b] [--free [--allow-training]] [--no-free]
 #   route-state.sh off
-#   route-state.sh set-rules <file.json>        replace rules[] from a JSON array
+#   route-state.sh set-rules <file.json>        replace rules[] from a JSON array,
+#                                               checked against the schema and cost table
 #
 # Exit codes:
 #   0  -  done
@@ -34,7 +35,7 @@ if [ -f "$_MA_RS_HERE/user-facing.sh" ]; then . "$_MA_RS_HERE/user-facing.sh"; e
 # included - through a third layer, breaks the subscription's auth model, and
 # silently changes which model answers. The schema encodes the same list so a
 # hand-edited preferences file is rejected too, rather than only this entry point.
-ALLOWED_SCOPE="subagent bulk-read research"
+ALLOWED_SCOPE="subagent bulk-read delegate research"
 
 die() { echo "route-state: $1" >&2; exit "${2:-3}"; }
 
@@ -47,6 +48,9 @@ jq -e . "$PREFS" >/dev/null 2>&1 || die "$PREFS is not valid JSON  -  refusing t
 
 ACTION="${1:-status}"; shift 2>/dev/null || true
 
+COST_TABLE="$_MA_RS_HERE/../scripts/cost-table.json"
+USAGE_LOG="${MCP_TOOLKIT_INDEX_DIR:-$HOME/.claude/logs/multi-agent-toolkit/.index}/llm-usage.jsonl"
+
 write_prefs() {
   local filter="$1"; shift
   local tmp
@@ -56,6 +60,57 @@ write_prefs() {
   mv "$tmp" "$PREFS"
 }
 
+# Last seven days of the toolkit's usage logs (attended, and an unattended run's
+# own under ~/.multi-agent-unattended): verified answers, cache hits and
+# escalations, and what those tokens would have cost on haiku, the rung bulk-read
+# and simple tasks fall back to. An estimate, and labelled as one.
+free_savings() {
+  local logs=() f
+  for f in "$USAGE_LOG" "$HOME/.multi-agent-unattended/toolkit-index/llm-usage.jsonl"; do
+    [ -f "$f" ] && logs+=("$f")
+  done
+  if [ "${#logs[@]}" -eq 0 ]; then
+    echo "savings: no free-model task recorded yet ($USAGE_LOG)"
+    return 0
+  fi
+  local since
+  since=$(( $(date +%s) - 7 * 86400 ))
+  jq -rs --argjson since "$since" --slurpfile ct "$COST_TABLE" '
+      map(select((.ts | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601? // 0) >= $since))
+    | ($ct[0].prices.haiku // {inPerMtok: 1, outPerMtok: 5}) as $h
+    | {
+        n: length,
+        ok: (map(select(.ok and (.cached | not))) | length),
+        cached: (map(select(.ok and .cached)) | length),
+        esc: (map(select(.ok | not)) | length),
+        pin: (map(.prompt_tokens // 0) | add // 0),
+        pout: (map(.completion_tokens // 0) | add // 0),
+        by: (map(select(.ok and .provider)) | group_by(.provider) | map("\(.[0].provider) \(length)") | join(", "))
+      }
+    | . + {usd: ((.pin * $h.inPerMtok + .pout * $h.outPerMtok) / 1000000)}
+    | "savings (7 days): \(.n) task(s), \(.ok) answered free and verified, \(.cached) from cache, \(.esc) handed back to Claude\n"
+      + "  tokens kept off Claude: \(.pin) in + \(.pout) out  (~$\(.usd * 100 | round / 100) at haiku rates, an estimate)"
+      + (if .by != "" then "\n  by provider: \(.by)" else "" end)
+  ' "${logs[@]}" 2>/dev/null || echo "savings: the usage log could not be read"
+}
+
+# What the toolkit can reach, without a single network call: configured
+# providers and where their keys come from. Names only, never values.
+free_providers() {
+  local tl="$_MA_RS_HERE/toolkit-llm.sh"
+  [ -f "$tl" ] || tl="$HOME/.claude/lib/toolkit-llm.sh"
+  [ -f "$tl" ] || { echo "free chain: toolkit-llm.sh is not installed"; return 1; }
+  # shellcheck source=/dev/null
+  . "$tl"
+  local out
+  out=$(ma_toolkit_llm providers ${1:+--allow-training} 2>/dev/null) || { echo "free chain: the multi-agent-toolkit CLI could not be run (node and npx are needed)"; return 1; }
+  jq -r '
+      "free chain: \(.configured) provider(s) usable under the \(.data_policy) data policy",
+      (.providers[] | "  \(if .configured and .allowed_by_policy then "ready  " elif .configured then "policy " else "missing" end) \(.id)\(if .key_source then " (" + .key_source + ")" else "" end)\(if (.configured | not) then "  -  " + .setup else "" end)")
+    ' <<< "$out"
+  [ "$(jq -r '.configured' <<< "$out")" -gt 0 ]
+}
+
 case "$ACTION" in
   status)
     ENABLED=$(jq -r '.global.modelRouting.enabled // false' "$PREFS")
@@ -63,12 +118,16 @@ case "$ACTION" in
     SCOPE=$(jq -r '(.global.modelRouting.scope // ["subagent"]) | join(", ")' "$PREFS")
     NRULES=$(jq -r '(.global.modelRouting.rules // []) | length' "$PREFS")
     CEIL=$(jq -r '.global.modelRouting.budgetCeilingUsd // "none"' "$PREFS")
-    REC=$(jq -r '.global.modelRouting.recordDecisions // true' "$PREFS")
+    REC=$(jq -r 'if .global.modelRouting.recordDecisions == false then "false" else "true" end' "$PREFS")
+
+    FREE=$(jq -r '.global.modelRouting.free.enabled // false' "$PREFS")
+    TRAIN=$(jq -r '.global.modelRouting.free.allowTraining // false' "$PREFS")
 
     echo "routing:   $ENABLED"
     echo "strategy:  $STRATEGY"
     echo "scope:     $SCOPE"
     echo "rules:     $NRULES"
+    echo "free:      $FREE$([ "$FREE" = "true" ] && echo " (data policy: $([ "$TRAIN" = "true" ] && echo any || echo no-training))")"
     echo "ceiling:   $CEIL"
     echo "decisions: $REC"
     echo ""
@@ -79,34 +138,46 @@ case "$ACTION" in
       exit 0
     fi
 
-    if [ "$NRULES" -eq 0 ]; then
+    if [ "$NRULES" -eq 0 ] && [ "$FREE" != "true" ]; then
       echo "Armed with no rules. Nothing matches, so nothing is routed  -  this is a"
       echo "configuration state, not an error."
-    else
+    elif [ "$NRULES" -gt 0 ]; then
       jq -r '(.global.modelRouting.rules // [])[] |
         "  when " + ([.when | to_entries[] | "\(.key)=\(.value)"] | join(" ")) +
         "  ->  " + (.prefer | join(" > "))' "$PREFS"
     fi
 
+    if [ "$FREE" = "true" ]; then
+      echo "  free chain first at: bulk-read, delegate (Anthropic default when it escalates)"
+      echo ""
+      free_savings
+    fi
+
     echo ""
     # The limit is printed every time rather than documented once, because the
     # question it answers ("routing is on, why is the reviewer still on Opus")
     # otherwise arrives days later as a bug report.
     echo "Honest limit: on Claude Code a subagent cannot be sent to a non-Anthropic"
     echo "model  -  subagent dispatch belongs to the host. Phase 1/2/3 personas stay"
-    echo "inside the Anthropic ladder whatever the rules say. External providers apply"
-    echo "only where this pipeline makes the call itself (bulk-read, research)."
+    echo "inside the Anthropic ladder whatever the rules say. Free models answer only"
+    echo "where this pipeline makes the call itself (bulk-read, delegate), only after"
+    echo "the toolkit verified the answer against its source, and Claude takes over"
+    echo "whenever none passes."
     ;;
 
   on)
-    STRATEGY="manual"; SCOPE_ARG=""
+    STRATEGY="manual"; SCOPE_ARG=""; FREE_ARG=""; TRAIN_ARG=false
     for arg in "$@"; do
       case "$arg" in
         --strategy=*) STRATEGY="${arg#*=}" ;;
         --scope=*)    SCOPE_ARG="${arg#*=}" ;;
+        --free)       FREE_ARG=on ;;
+        --no-free)    FREE_ARG=off ;;
+        --allow-training) TRAIN_ARG=true ;;
         *) die "unknown option: $arg" 2 ;;
       esac
     done
+    [ "$TRAIN_ARG" = "true" ] && [ "$FREE_ARG" != "on" ] && die "--allow-training only goes with --free" 2
     case "$STRATEGY" in
       manual|task-fit|cost-ceiling) ;;
       *) die "strategy must be manual, task-fit or cost-ceiling (got '$STRATEGY')" 2 ;;
@@ -138,6 +209,26 @@ case "$ACTION" in
         | .global.modelRouting.scope //= ["subagent"]
       ' --arg st "$STRATEGY"
     fi
+    if [ "$FREE_ARG" = "on" ]; then
+      write_prefs '
+          .global.modelRouting.free = {enabled: true, allowTraining: $tr}
+        | .global.modelRouting.scope = (((.global.modelRouting.scope // ["subagent"]) + ["bulk-read", "delegate"]) | unique)
+      ' --argjson tr "$TRAIN_ARG"
+      echo "free chain enabled at bulk-read and delegate (data policy: $([ "$TRAIN_ARG" = "true" ] && echo any || echo no-training))"
+      TRAIN_FLAG=""
+      [ "$TRAIN_ARG" = "true" ] && TRAIN_FLAG=1
+      if ! free_providers "$TRAIN_FLAG"; then
+        echo ""
+        echo "No free provider is usable yet, so every task still runs on Claude. Add one key"
+        echo "(free at https://console.groq.com/keys) with $(ma_command setup), or from a shell:"
+        echo "  bash \"\$HOME/.claude/lib/credential-store.sh\" set llm-groq -    (paste the key, then Ctrl-D)"
+        echo "or export GROQ_API_KEY for the server, then run $(ma_command route-status)."
+      fi
+      echo ""
+    elif [ "$FREE_ARG" = "off" ]; then
+      write_prefs '.global.modelRouting.free.enabled = false'
+      echo "free chain disabled; Anthropic rungs only"
+    fi
     echo "routing enabled (strategy: $STRATEGY)"
     exec "$0" status
     ;;
@@ -154,6 +245,23 @@ case "$ACTION" in
     [ -n "$FILE" ] || die "set-rules needs a JSON file containing an array of rules" 2
     [ -f "$FILE" ] || die "no such file: $FILE" 2
     jq -e 'type == "array"' "$FILE" >/dev/null 2>&1 || die "$FILE must contain a JSON ARRAY of rules" 2
+    # The schema's rule shape, enforced here so a hand-written file cannot store
+    # a rule that dispatch silently skips: when has 1-3 known keys with valid
+    # values, prefer is a non-empty list of rungs the cost table prices.
+    RUNGS=$(jq -c '.prices | keys' "$COST_TABLE" 2>/dev/null || echo '[]')
+    BAD=$(jq -r --argjson rungs "$RUNGS" '
+        to_entries[] | .key as $i | .value as $r
+      | if ($r | type) != "object" then "rule \($i): not an object"
+        elif (($r | keys) - ["when", "prefer"]) != [] then "rule \($i): unknown key(s) \((($r | keys) - ["when", "prefer"]) | join(", "))"
+        elif ($r.when | type) != "object" or ($r.when | length) == 0 then "rule \($i): when needs persona, phase or taskKind"
+        elif (($r.when | keys) - ["persona", "phase", "taskKind"]) != [] then "rule \($i): when has unknown key(s) \((($r.when | keys) - ["persona", "phase", "taskKind"]) | join(", "))"
+        elif ($r.when.persona != null and ($r.when.persona | type) != "string") then "rule \($i): persona must be a string"
+        elif ($r.when.phase != null and (($r.when.phase | type) != "number" or $r.when.phase < 0 or $r.when.phase > 5 or ($r.when.phase | floor) != $r.when.phase)) then "rule \($i): phase must be an integer 0-5"
+        elif ($r.when.taskKind != null and ([$r.when.taskKind] | inside(["bugfix", "feature", "refactor", "chore", "component"]) | not)) then "rule \($i): taskKind must be bugfix, feature, refactor, chore or component"
+        elif ($r.prefer | type) != "array" or ($r.prefer | length) == 0 then "rule \($i): prefer needs at least one rung"
+        elif ([$r.prefer[] | select((type != "string") or (. as $x | $rungs | index($x) | not))] | length) > 0 then "rule \($i): unknown rung(s) \([$r.prefer[] | select((type != "string") or (. as $x | $rungs | index($x) | not))] | map(tostring) | join(", ")) (known: \($rungs | join(", ")))"
+        else empty end' "$FILE" 2>/dev/null)
+    [ -z "$BAD" ] || die "$(printf 'rules rejected, nothing written:\n%s' "$BAD")" 2
     write_prefs '.global.modelRouting //= {} | .global.modelRouting.rules = $r' --slurpfile _ignore /dev/null --argjson r "$(cat "$FILE")"
     echo "rules replaced: $(jq -r 'length' "$FILE")"
     ;;

package/pipeline/lib/toolkit-llm.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# toolkit-llm.sh  -  run the multi-agent-toolkit's free-model CLI.
+#
+# Sourced by bulk-read.sh and route-state.sh. `ma_toolkit_llm <args>` runs
+# `multi-agent-toolkit-llm <args>` from the first place it exists:
+#
+#   1. MULTI_AGENT_TOOLKIT_LLM            a path to the CLI script
+#   2. multi-agent-toolkit-llm on PATH    a global install
+#   3. npx -p @mmerterden/multi-agent-toolkit-mcp@latest, the same package
+#      the MCP registration runs
+#
+# A maintainer's working copy (prefs.global.devToolkit) is deliberately not a
+# source: it can sit on an unreleased branch, and a run should use what ships.
+#
+# The CLI prints one JSON object and exits 0 on a verified answer, 3 on
+# ESCALATE_TO_CLAUDE, 2 on a usage error. Any other status (no node, no network
+# for npx) is the caller's cue to keep its own default.
+
+ma_toolkit_llm() {
+  if [ -n "${MULTI_AGENT_TOOLKIT_LLM:-}" ] && [ -f "$MULTI_AGENT_TOOLKIT_LLM" ]; then
+    node "$MULTI_AGENT_TOOLKIT_LLM" "$@"
+    return $?
+  fi
+  if command -v multi-agent-toolkit-llm >/dev/null 2>&1; then
+    multi-agent-toolkit-llm "$@"
+    return $?
+  fi
+  command -v npx >/dev/null 2>&1 || return 127
+  npx -y --@mmerterden:registry=https://registry.npmjs.org -p @mmerterden/multi-agent-toolkit-mcp@latest multi-agent-toolkit-llm "$@"
+}

package/pipeline/lib/unattended-profile-check.mjs

@@ -22,9 +22,22 @@ import { join } from "node:path";
 
 const PREFS_HOST_KEYS = ["jira", "confluence", "bitbucket"];
 
+// The free-model hosts a sandboxed bulk-read may reach once route-on --free is
+// on: Groq alone under the default no-training policy, all five with
+// allowTraining. A local Ollama needs no host; allowLocalBinding covers it.
+const FREE_HOSTS_NO_TRAINING = ["api.groq.com"];
+const FREE_HOSTS_ANY = [
+  "api.groq.com",
+  "api.mistral.ai",
+  "generativelanguage.googleapis.com",
+  "openrouter.ai",
+  "api.z.ai",
+];
+
 /**
  * Hosts from prefs.global.hosts, so the sandbox's network list covers this
- * machine's own Jira / Confluence / Bitbucket.
+ * machine's own Jira / Confluence / Bitbucket, plus the free-model providers
+ * modelRouting.free allows.
  *
  * @param {string} home
  * @returns {string[]}
@@ -35,7 +48,7 @@ export function prefsHosts(home) {
       readFileSync(join(home, ".claude", "multi-agent-preferences.json"), "utf-8"),
     );
     const hosts = prefs?.global?.hosts || {};
-    return PREFS_HOST_KEYS.map((k) => hosts[k])
+    const own = PREFS_HOST_KEYS.map((k) => hosts[k])
       .filter((v) => typeof v === "string" && v.trim())
       .map(
         (v) =>
@@ -44,6 +57,14 @@ export function prefsHosts(home) {
             .replace(/^[a-z]+:\/\//i, "")
             .split("/")[0],
       );
+    const routing = prefs?.global?.modelRouting;
+    const free =
+      routing?.enabled === true && routing?.free?.enabled === true
+        ? routing.free.allowTraining === true
+          ? FREE_HOSTS_ANY
+          : FREE_HOSTS_NO_TRAINING
+        : [];
+    return [...own, ...free];
   } catch {
     return [];
   }

package/pipeline/multi-agent-refs/analysis/evidence.md

@@ -27,6 +27,8 @@ For each entry in `state.analysisSpec.contextLinks[]`, fan out by `type`. Entrie
 2. Surface a one-line warning to the user during Phase 1 progress output: `WARN: Confluence requires browser auth for <url>. Falling back to repo evidence; add the page text manually to /tmp/analysis-paste.md and re-run if needed.`
 3. Continue Phase 1 with remaining evidence sources rather than aborting.
 
+**Long sources:** with the free chain on, summarize long confluence/document/jira/generic-doc texts via `llm_delegate` first (`features/free-models.md`).
+
 For each repo in `state.analysisSpec.repos[]`, run parallel greps (lightweight surface scan; the deeper 13-bucket extraction happens in Phase 1b):
 
 ```bash
@@ -204,7 +206,7 @@ Phase 2 Section 20 Risks reads this list and emits one open question per entry.
 
 **Caching (Locked 26)**: compute `evidence_digest = sha256(featureName || sorted(platforms) || options.redesign || hash(evidence.repoEvidence) || hash(evidence.conventions))`. `options.redesign` is a digest input: without it a redesign within a day of a normal run on the same feature reuses that cache, skips Phase 1b, and renders an empty current-behaviour table every redesign check then passes over. Cache key on disk: `/tmp/multi-agent-analysis-cache/<digest>.json` with mtime <= 24h. Cache hit skips Phase 1b and Phase 1c. `--no-cache` flag forces re-run.
 
-Phase 1d is deliberately absent from the digest inputs. Community signal changes by the hour, so folding it in would produce a new digest on every run, invalidate the cache every time, and re-run the two expensive repo phases the cache exists to skip. The consequence is worth stating plainly: a cache hit reuses yesterday's signal rows. That is the correct trade for an advisory tier, and `--no-cache` is the way to refresh them.
+Phase 1d is not a digest input: community signal changes hourly, so it would invalidate the cache every run and re-run the two costly repo phases the cache skips. A cache hit reuses yesterday's signal rows, the right trade for an advisory tier; `--no-cache` refreshes them.
 
 ### Phase 1d - Outside facts (optional, analyst toolkit)
 

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -115,6 +115,7 @@ it does not. Contracts: `features/exploratory-testing.md`,
 | Web states and locators | `web_route`, `web_network_state`, `web_clock`, `web_dialog`, `web_upload`, `web_drag`, `web_hover`, `web_fill_form`, `web_find`, `web_generate_locator`, `web_trace`; `request_id` on `web_network`; `locator` on `web_click` / `web_type` | ≥ v3.20.0 |
 | Document fetch and crawl | `web_scrape` (formats, cache, `change_tracking`), `url` / `sitemap` / `include_paths` / `llms_txt` on `web_crawl` and `web_map` | ≥ v3.20.0 |
 | Research modes and threads | `mode`, `recency`, `domains`, `sources`, `thread_id` on `research_ask`; `arxiv` and `fetch_content` on `research_search` | ≥ v3.20.0 |
+| Free-model delegation | `llm_delegate`, `llm_providers`; `ESCALATE_TO_CLAUDE`; the `multi-agent-toolkit-llm` CLI (`delegate`, `providers`, `probe`, `usage`) | ≥ v3.21.0 |
 
 ---
 
@@ -270,9 +271,13 @@ happen.
 The routing trio (`route-on`, `route-off`, `route-status`) has no such split -
 it writes `prefs.global.modelRouting` identically everywhere. Its honest limit is
 different and applies on every host: a subagent cannot be dispatched to a
-non-Anthropic model, because subagent dispatch belongs to the host. External
-providers are reachable only where the pipeline makes the HTTP call itself
-(`bulk-read.sh`, `research_ask`). `route-status` prints that on every run.
+non-Anthropic model, because subagent dispatch belongs to the host. The `free`
+rung (`route-on --free`) is reachable only where the pipeline makes the call
+itself: `bulk-read.sh` and the `delegate` call site, where a skill asks
+`model-dispatch.sh delegate --default host` and calls `llm_delegate` on `free`.
+The toolkit and its CLI are the same on all three hosts, so the free chain
+behaves identically everywhere. `route-status` prints the limit on every run.
+Contract: `features/free-models.md`.
 
 ## 3. Frontmatter Transform Rules (Claude ↔ Copilot)
 

package/pipeline/multi-agent-refs/features/doctor.md

@@ -303,6 +303,17 @@ other outcome (`redirected`, `rejected`, `not-accepted`, `failed`, `skipped`),
 with the status code or reason and the step that fixes it. The emitter runs
 detached from phase-tracker with its output discarded, so this record is the
 only surface on which a reporting path that stopped working shows up.
+### free-models
+
+Can `route-on --free` actually leave Claude. SKIP while routing or its free
+chain is off. Otherwise it runs the toolkit's `multi-agent-toolkit-llm
+providers` through `lib/toolkit-llm.sh`: WARN when the CLI cannot run, or when
+no provider is both configured and allowed by the data policy
+(`modelRouting.free.allowTraining`), because every free task then escalates to
+Claude while the user believes it does not. `--probe` also sends each
+configured provider one tiny request and WARNs when every usable one fails it
+(a revoked key, an exhausted quota). `--explain` lists each provider with its
+key source, never a value.
 ### xcode-skills
 
 Is Apple's `xcode-integration` plugin, which Xcode 27.1 and later materialize

package/pipeline/multi-agent-refs/features/free-models.md

@@ -0,0 +1,111 @@
+# Free models: the `free` rung and the `delegate` call site
+
+<!-- toc -->
+- [Turning it on](#turning-it-on)
+- [The two call sites](#the-two-call-sites)
+- [What `delegate` may hand over](#what-delegate-may-hand-over)
+- [The contract with the answer](#the-contract-with-the-answer)
+- [Unattended runs](#unattended-runs)
+- [Requirements](#requirements)
+<!-- /toc -->
+
+Layer 2 of model routing. With `/multi-agent:route-on --free`, simple text work
+that the pipeline does itself goes to the multi-agent-toolkit's verified
+free-model chain instead of a Claude rung. Decisions, plans, code, reviews,
+triage and security judgements never do.
+
+Off by default. Nothing here changes a run until routing and its free chain are
+both on.
+
+## Turning it on
+
+```bash
+bash "$HOME/.claude/lib/route-state.sh" on --free                    # Groq and a local Ollama only
+bash "$HOME/.claude/lib/route-state.sh" on --free --allow-training   # also Mistral, Gemini, OpenRouter free, Z.AI
+```
+
+`--free` sets `modelRouting.free.enabled`, adds `bulk-read` and `delegate` to
+`scope`, and lists which providers are usable. One free key is enough to start:
+Groq's (<https://console.groq.com/keys>), stored with `/multi-agent:setup` or
+`credential-store.sh set llm-groq -`, or exported as `GROQ_API_KEY` for the
+server. `/multi-agent:route-status` reports the last seven days: tasks answered
+free and verified, tasks handed back to Claude, and the tokens kept off Claude.
+`/multi-agent:doctor` warns when the switch is on and no provider is usable;
+`--probe` sends each provider one tiny request.
+
+**Data policy.** `allowTraining: false` (the default) keeps text to providers
+whose free tier does not train on prompts (Groq) and a local Ollama.
+`--allow-training` adds free tiers that may train on prompts or whose data use
+is not stated. Corporate source, tickets and logs belong under the default.
+
+## The two call sites
+
+| Call site | Who calls | What goes free | Fallback |
+|---|---|---|---|
+| `bulk-read` | `bulk-read.sh`, when the read gate diverts a large file | the line-numbered summary of one file, validated against `schemas/bulk-read-output.schema.json` and the file's line count | `claude -p --model <bulkRead.model or haiku>` |
+| `delegate` | a skill or phase, through the `llm_delegate` MCP tool | one of the simple tasks below | the session does the task itself |
+
+Both ask the router first, so the policy has one implementation:
+
+```bash
+bash "$HOME/.claude/lib/model-dispatch.sh" delegate --default host   # prints `free` or `host`
+```
+
+`free` means call `llm_delegate`; anything else means do the task in-session as
+before. A subagent is dispatched by the host, so the router never answers `free`
+for one.
+
+## What `delegate` may hand over
+
+Only tasks whose answer can be checked against their own source:
+
+| Task | `llm_delegate` | Development | Analysis |
+|---|---|---|---|
+| Summarize a long text | `task: summarize` | build and test logs, crash logs, a long file the plan only needs the shape of | Confluence pages, Swagger descriptions, Jira descriptions and comment threads, `generic-doc` links fetched through `web_scrape`, research documents |
+| Pull named fields out of a text | `task: extract` with a `schema` | ticket keys, endpoints, error codes, failing test names from a log | acceptance criteria, endpoints and field lists, dates and owners from a document |
+| Pick one label | `task: classify` with `labels` | commit type from a diff summary, a log line's severity | issue type, affected platform, a comment's intent |
+| Translate a draft | `task: translate` | localization drafts for review (the resources repo stays the contract) | a source document into the output language |
+| Write a draft from a source | `task: draft` | a commit body or PR description draft from the diff summary, then the humanizer | a section draft the analysis author then edits |
+
+In analysis Phase 1, a fetched `confluence`, `document`, `generic-doc` or
+`jira` text longer than about 8,000 characters is summarized before it is
+reasoned over: ask the router once per run, then `extract` with a schema for
+the fields a section needs (acceptance criteria, endpoints, field lists, dates,
+owners) and `summarize` for the rest. The verified answer is the working copy
+for drafting; the raw fetch stays in its evidence bucket and Section 21 still
+cites the source. `binding: true` standards are never delegated: their wording
+is the requirement.
+
+Never handed over: deciding what to build, the plan, any code or diff, review
+findings and triage, security or licence judgements, anything written to a
+ticket, PR or channel without the session reading it first.
+
+## The contract with the answer
+
+- A verified answer is still a third-party model's text. It comes back fenced
+  as untrusted; the session reads it as data and checks it against the plan
+  like any other input.
+- `ESCALATE_TO_CLAUDE` is not an error. It lists a reason per provider; the
+  session does the task itself and the run continues. Nothing is retried in a
+  loop and no weaker answer is substituted.
+- The toolkit scrubs key-shaped strings before anything leaves the machine.
+  Text that must not leave the machine at all (credentials, personal data,
+  customer records) is not delegated, whatever the policy says.
+
+## Unattended runs
+
+`llm_delegate` runs in the MCP server, outside the run's OS sandbox, and reads
+provider keys from the credential store; agent-guard allows it only while
+`route-on --free` is on. `bulk-read.sh` runs inside the sandbox, which cannot
+read the Keychain: it uses the free chain only when the provider key is in the
+run's environment, keeps the toolkit's quota and usage files under
+`~/.multi-agent-unattended/toolkit-index`, and reads on haiku otherwise. The
+installer adds the allowed provider hosts to the sandbox network list
+(`lib/unattended-profile-check.mjs` `prefsHosts`) when the free chain is on;
+re-run `install --unattended` after turning it on.
+
+## Requirements
+
+`@mmerterden/multi-agent-toolkit-mcp` ≥ v3.21.0 (`llm_delegate`,
+`llm_providers`, the `multi-agent-toolkit-llm` CLI). `lib/toolkit-llm.sh` finds
+the CLI through `MULTI_AGENT_TOOLKIT_LLM`, then `PATH`, then `npx`.

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -199,8 +199,9 @@ per-phase `model` field already carries the override).
 ## Routing at dispatch
 
 `$HOME/.claude/lib/model-dispatch.sh` turns `prefs.global.modelRouting` into a
-rung. Two call sites ask it: the subagent dispatch contract in
-`skills/shared/core/multi-agent/SKILL.md`, and `bulk-read.sh`.
+rung. Three call sites ask it: the subagent dispatch contract in
+`skills/shared/core/multi-agent/SKILL.md`, `bulk-read.sh`, and the `delegate`
+call site for simple text tasks (`features/free-models.md`).
 
 Routing is consulted only when the phase named no model. A per-dispatch
 `PHASE_MODEL_OVERRIDE` is a decision the phase made for a reason - Phase 3 sets
@@ -212,17 +213,22 @@ Two limits are enforced by the script rather than written here and hoped for:
 - **A rule may not turn the fable rung on.** With `modelFallback.fableEnabled`
   false, a rule preferring `fable` falls past it to the next rung. Otherwise
   `/multi-agent:model off` would have a second door.
-- **Every call site stays inside the Anthropic ladder.** No call site can
-  dispatch to another provider today: a subagent is dispatched by the host,
-  `bulk-read.sh` shells out to `claude -p --model <rung>`, and `research_ask`
-  runs in the MCP server and picks its own model. A rule preferring an external
-  rung falls to the next rung the rule named, and the script says why on stderr.
-  Returning the external rung instead would hand a caller a name it passes
-  straight to a CLI that does not know it - a failed call, not a cheaper one.
-  `provider` in `cost-table.json` is what makes the refusal checkable and is the
-  seam a future call site would use; `smoke-model-dispatch.sh` asserts that
-  `bulk-read.sh` still dispatches through the Anthropic CLI, so the day that
-  changes, the gate says the refusal may be lifted.
+- **A subagent stays inside the Anthropic ladder.** A subagent is dispatched by
+  the host, so `free` and every other non-Anthropic rung is refused at the
+  subagent site and the rule's next rung answers, with the reason on stderr.
+- **`free` only where the pipeline makes the call, and only when switched on.**
+  The `free` rung (provider `free-chain`) answers at `bulk-read` and `delegate`
+  while `modelRouting.free.enabled` is true (`route-on --free`), ahead of the
+  matched rule's rungs. Its callers keep their own default as the fallback,
+  because the toolkit answers `ESCALATE_TO_CLAUDE` whenever no free answer
+  survives verification. Any other external rung (the `gpt-*` rows) is refused
+  everywhere: no call site speaks it.
+
+Strategies change the order of the candidate rungs, never the set: `task-fit`
+tries the cheapest first by `cost-table.json` price, and `cost-ceiling` does the
+same once `cost-budget-check.mjs` reports the run at the warn threshold of
+`budgetCeilingUsd`. `recordDecisions: false` is honoured; `true` (the default)
+logs each decision as `model_routing.decision`.
 
 The script never fails and never returns an empty rung: a missing preferences
 file, a missing `jq`, unparseable JSON, an out-of-scope call site and a rung
@@ -231,8 +237,8 @@ router that can die would turn every call site into a place the run can die, for
 a feature that ships disabled.
 
 `cost-table.json` rows carry a `provider`, which is what tells the two layers
-apart. `smoke-model-dispatch.sh` drives the script and also asserts that the two
-call sites invoke it: a correct router nothing calls is the same outage with
+apart. `smoke-model-dispatch.sh` drives the script and also asserts that the call
+sites invoke it: a correct router nothing calls is the same outage with
 better internals.
 
 ## Non-goals

package/pipeline/multi-agent-refs/features/unattended-security.md

@@ -188,7 +188,7 @@ Under the variable it also blocks:
 | Publisher scripts | `jira-publish.sh`, `post-pr-review.sh`, `update-issue-progress.sh`, `analysis-jira-write.sh`, `jira-attach.sh`, `md2confluence-v3.py create/update`, `multi-repo-pipeline.sh push/pr`, `keychain-save.sh`, `credential-store.sh get/set/delete`, `keychain.py get/set/delete`, `gate-ledger.mjs append`, `phone-devices.mjs add/revoke/launch` | the same, a credential never lands in the transcript, gates record verdicts through their own in-process calls (`park` stays allowed: it only stops the run, so there is nothing to forge), and a run never enrols a device that could then command this machine |
 | Git redirection | `git remote add/set-url/rename/remove`; the configuration, environment and subcommands above | each changes what a later command runs or where the runner's push goes |
 | Keychain | `security find-*`, `dump-keychain`, `export`, `add-*password`, `delete-*password`, also behind leading flags (`security -q find-generic-password`) | a run needs no credential it did not get from a fetcher |
-| Network | `curl`/`wget`/`WebFetch`/the toolkit's `web_*` tools to a host outside the allowlist, or to a URL built at run time; `web_eval` outright; every step of `agent_run_steps` judged as if called directly (a nested `agent_*` step or an unreadable step list refused); `ios_open_url` / `android_open_url`, `xcrun simctl openurl` and `open` with a web URL outside the allowlist (an app's own deep-link scheme passes; `open` of anything but an allowed URL is refused); the `research_*` tools outright | an injected "fetch this script" is the first step of most attacks, and a browser opened on a crafted URL sends data out in the query |
+| Network | `curl`/`wget`/`WebFetch`/the toolkit's `web_*` tools to a host outside the allowlist, or to a URL built at run time; `web_eval` outright; every step of `agent_run_steps` judged as if called directly (a nested `agent_*` step or an unreadable step list refused); `ios_open_url` / `android_open_url`, `xcrun simctl openurl` and `open` with a web URL outside the allowlist (an app's own deep-link scheme passes; `open` of anything but an allowed URL is refused); the `research_*` tools outright; `llm_delegate` unless `route-on --free` is on, with its `path` checked like any write target | an injected "fetch this script" is the first step of most attacks, and a browser opened on a crafted URL sends data out in the query |
 | Packages | `npm/pnpm/yarn/bun install|add <pkg>`, `npm install-test/it <pkg>`, `update`, global installs (`yarn global` too), `npx` / `npm exec` / `npm x` of a binary not already in `node_modules/.bin` (with no TTY npm installs it without asking), `npx --yes/--package/--call`, `pnpm dlx`, `pnpx`, `yarn dlx`, `bunx`, `bun x`, `uvx`, `uv tool run/install`, `pipx run/install`, `pip install <pkg>`, `uv/poetry add`, `gem install`, `bundle add`, `brew install`, `cargo add/install`, `go get`, `go install pkg@v`, `swift package add-dependency`, `pod update`; `npm ci`, `pod install` and `pip install -r` once the run changed the manifest they restore from | slopsquatting: a model asked to add a dependency can name one that does not exist yet, and someone can register it |
 | Host changes | `crontab` (except `-l`), `launchctl` (except the read verbs), `defaults` writes, `altool`, `notarytool` | a job or preference outlives the run and runs as the operator; an upload is outward |
 | Manifests | Edit, Write or a shell write to `Package.swift`, `Package.resolved`, `package.json`, lockfiles, `Podfile(.lock)`, `build.gradle(.kts)`, `settings.gradle(.kts)`, `libs.versions.toml`, `requirements*.txt`, `pyproject.toml`, `go.mod`/`go.sum`, `Cargo.toml`/`Cargo.lock`, `Gemfile(.lock)` | the same decision, made through the file instead of the command |
@@ -512,7 +512,9 @@ every process it starts, whatever the command line looks like.
   `~/.netrc`, `~/.git-credentials` and `~/.docker/config.json`.
 - `network.strictAllowlist: true` with `allowedDomains` limited to the package
   registries and toolchains the stack adapters need (npm, PyPI, Maven/Google/
-  Gradle, CocoaPods, Go, crates, RubyGems, GitHub) plus the prefs hosts.
+  Gradle, CocoaPods, Go, crates, RubyGems, GitHub) plus the prefs hosts, and,
+  while `route-on --free` is on, the free-model hosts its data policy allows
+  (`api.groq.com` alone by default; `features/free-models.md`).
   `enableWeakerNetworkIsolation: true` lets Go tools such as `gh` reach the
   macOS trust service to verify TLS; `allowLocalBinding` and
   `allowMachLookup: ["com.apple.coresimulator.*"]` let a dev server and the

package/pipeline/multi-agent-refs/setup/free-models.md

@@ -0,0 +1,22 @@
+# Setup Step 3e - free-model keys
+
+Runs inside setup Step 3, only when `prefs.global.modelRouting.free.enabled` is
+true (`/multi-agent:route-on --free`). These are the keys the toolkit's
+free-model chain reads; `llm_delegate` and `bulk-read.sh` look for them under
+fixed names, so there is no `keychainMapping` entry.
+
+| Key | Provider | Where to get it | Asked |
+|---|---|---|---|
+| `llm-groq` | Groq (free tier does not train on prompts) | https://console.groq.com/keys | always first |
+| `llm-mistral` | Mistral | https://console.mistral.ai/api-keys | only with `modelRouting.free.allowTraining` |
+| `llm-gemini` | Google Gemini | https://aistudio.google.com/apikey | only with `allowTraining` |
+| `llm-openrouter` | OpenRouter, free models only | https://openrouter.ai/keys | only with `allowTraining` |
+| `llm-zai` | Z.AI GLM Flash | https://z.ai/manage-apikey/apikey-list | only with `allowTraining` |
+
+Each key is one Token Save Flow pass (`token-save-flow.md`) with the clipboard
+save, `pbpaste | credential-store.sh set "<key>" -`, and no author or host step.
+Skip writes nothing and moves to the next key. After the last pass, run
+`route-state.sh status` so the user sees each saved provider reported ready.
+
+A local Ollama needs no key: the user sets `OLLAMA_MODEL` for the server. The
+full contract: `$HOME/.claude/multi-agent-refs/features/free-models.md`.

package/pipeline/preferences-template.json

@@ -79,6 +79,7 @@
       "strategy": "manual",
       "scope": ["subagent"],
       "rules": [],
+      "free": { "enabled": false, "allowTraining": false },
       "budgetCeilingUsd": null,
       "recordDecisions": true
     },

package/pipeline/schemas/prefs.schema.json

@@ -599,10 +599,19 @@
               "uniqueItems": true,
               "items": {
                 "type": "string",
-                "enum": ["subagent", "bulk-read", "research"]
+                "enum": ["subagent", "bulk-read", "delegate", "research"]
               },
               "description": "No host-session member, deliberately: rewriting the host's base URL would route the user's whole session, not just this pipeline's calls."
             },
+            "free": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Layer 2: the verified free-model chain at bulk-read and delegate. Contract: route-config.schema.json.",
+              "properties": {
+                "enabled": { "type": "boolean", "default": false },
+                "allowTraining": { "type": "boolean", "default": false }
+              }
+            },
             "rules": {
               "type": "array",
               "default": [],