@mmerterden/multi-agent-pipeline 20.20.0 → 20.21.0

package/pipeline/schemas/route-config.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/route-config.schema.json",
   "title": "Model routing configuration",
-  "description": "Policy-driven model selection, OFF by default. Lives under prefs.global.modelRouting. Two layers, and the difference is the whole safety argument. Layer 1 chooses a rung INSIDE the Anthropic ladder and writes to the existing PHASE_MODEL_OVERRIDE seam - no new network path, no new account. Layer 2 would send a call to a non-Anthropic provider, and no call site can do that yet: 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. model-dispatch.sh therefore refuses a non-Anthropic rung everywhere and falls to the rule's next rung, because an allowed rung nothing can honour is a rule the user believes worked. `provider` in cost-table.json is the seam a future call site would use. `scope` has no `host-session` member and that absence is enforced here rather than written in prose: rewriting the host's base URL would route the user's ENTIRE session, including work that has nothing to do with this pipeline, through a third layer - breaking the subscription's auth model and silently changing which model answers. Shipping this disabled is the same reasoning as modelFallback.fableEnabled: a cost control that is on by default is not a control.",
+  "description": "Policy-driven model selection, OFF by default. Lives under prefs.global.modelRouting. Two layers, and the difference is the whole safety argument. Layer 1 chooses a rung INSIDE the Anthropic ladder and writes to the existing PHASE_MODEL_OVERRIDE seam - no new network path, no new account. Layer 2 is the `free` rung: a simple text task (a bulk read, a summary, an extraction, a label, a translation draft) goes to the multi-agent-toolkit's verified free-model chain (llm_delegate / multi-agent-toolkit-llm), whose every answer is checked against its source and discarded when it does not hold, with the Anthropic default taking over. It is reachable only where the pipeline makes the call itself (`bulk-read`, `delegate`); a subagent is dispatched by the host, so model-dispatch.sh refuses `free` and every other non-Anthropic rung at the subagent site and falls to the rule's next rung. `scope` has no `host-session` member and that absence is enforced here rather than written in prose: rewriting the host's base URL would route the user's ENTIRE session, including work that has nothing to do with this pipeline, through a third layer - breaking the subscription's auth model and silently changing which model answers. Shipping this disabled is the same reasoning as modelFallback.fableEnabled: a cost control that is on by default is not a control.",
   "type": "object",
   "additionalProperties": false,
   "required": ["enabled"],
@@ -16,16 +16,16 @@
       "type": "string",
       "enum": ["manual", "task-fit", "cost-ceiling"],
       "default": "manual",
-      "description": "manual: only the explicit rules[] apply, nothing is inferred. task-fit: a rule may match on taskKind and the router picks the cheapest rung that clears it. cost-ceiling: rungs downgrade as the run approaches budgetCeilingUsd."
+      "description": "manual: only the explicit rules[] apply, nothing is inferred. task-fit: the matched rule's rungs are tried cheapest first (cost-table.json prices, free first). cost-ceiling: rules apply in order until the run reaches the warn threshold of budgetCeilingUsd, then the cheapest rung is tried first."
     },
     "scope": {
       "type": "array",
       "default": ["subagent"],
       "uniqueItems": true,
-      "description": "Where routing is allowed to act. Every member names a call site the pipeline itself owns. There is deliberately no `host-session` member - see the title description.",
+      "description": "Where routing is allowed to act. Every member names a call site the pipeline itself owns: subagent (persona dispatch, Anthropic rungs only), bulk-read (bulk-read.sh), delegate (simple text tasks the skills hand to llm_delegate), research. There is deliberately no `host-session` member - see the title description.",
       "items": {
         "type": "string",
-        "enum": ["subagent", "bulk-read", "research"]
+        "enum": ["subagent", "bulk-read", "delegate", "research"]
       }
     },
     "rules": {
@@ -42,8 +42,14 @@
             "additionalProperties": false,
             "minProperties": 1,
             "properties": {
-              "persona": { "type": "string" },
-              "phase": { "type": "integer", "minimum": 0, "maximum": 5 },
+              "persona": {
+                "type": "string"
+              },
+              "phase": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 5
+              },
               "taskKind": {
                 "type": "string",
                 "enum": ["bugfix", "feature", "refactor", "chore", "component"]
@@ -54,16 +60,35 @@
             "type": "array",
             "minItems": 1,
             "description": "Rungs in descending preference. Rung NAMES are the contract; model ids are not - they live in cost-table.json and change without a config edit.",
-            "items": { "type": "string" }
+            "items": {
+              "type": "string"
+            }
           }
         }
       }
     },
+    "free": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Layer 2. With enabled:true, the bulk-read and delegate call sites try the free rung before the rule's Anthropic rungs. Written by route-on --free.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Try the verified free-model chain first at bulk-read and delegate. Ships false."
+        },
+        "allowTraining": {
+          "type": "boolean",
+          "default": false,
+          "description": "Also use free tiers that may train on prompts (Mistral, Gemini) or whose data use is unknown. false keeps text to providers that do not (Groq) and a local Ollama."
+        }
+      }
+    },
     "budgetCeilingUsd": {
       "type": ["number", "null"],
       "default": null,
       "minimum": 0,
-      "description": "Only consulted by the cost-ceiling strategy. null means no ceiling, which is not the same as a ceiling of 0."
+      "description": "Only consulted by the cost-ceiling strategy, through cost-budget-check.mjs against the run's tracker. null means no ceiling, which is not the same as a ceiling of 0."
     },
     "recordDecisions": {
       "type": "boolean",

package/pipeline/schemas/secret-patterns.json

@@ -78,6 +78,20 @@
       "len": 36,
       "suffix": ""
     },
+    {
+      "id": "groq",
+      "prefix": "gsk_",
+      "fill": "A",
+      "len": 52,
+      "suffix": ""
+    },
+    {
+      "id": "openrouter",
+      "prefix": "sk-or-v1-",
+      "fill": "a",
+      "len": 64,
+      "suffix": ""
+    },
     {
       "id": "huggingface",
       "prefix": "hf_",

package/pipeline/scripts/bulk-read.sh

@@ -91,11 +91,12 @@ if command -v jq >/dev/null 2>&1; then
 fi
 [ -n "$MODEL" ] || MODEL="${PREF_MODEL:-haiku}"
 
-# Routing picks the rung INSIDE the Anthropic ladder. The worker below is the
-# `claude` CLI, which speaks that ladder and nothing else, so a rung on another
-# provider is refused at dispatch rather than returned and failed. Sending this
-# read to a third-party provider would put the file's full text outside the
-# account that owns it, and that is a decision a user makes, not a default.
+# Routing picks the rung. An Anthropic rung goes to the `claude` CLI below. The
+# `free` rung (route-on --free) goes to the multi-agent-toolkit's verified
+# free-model chain first, and the Anthropic default answers whenever that chain
+# escalates or is unreachable. Sending this read to a free provider puts the
+# file's text outside the account that owns it, which is why it happens only
+# after a user turned it on, and only to providers the data policy allows.
 # An explicit --model still wins: a caller that named a rung asked for that rung.
 if [ -z "${MODEL_EXPLICIT:-}" ] && [ -x "$HERE/../lib/model-dispatch.sh" ]; then
   MODEL=$("$HERE/../lib/model-dispatch.sh" bulk-read \
@@ -104,7 +105,9 @@ fi
 case "$TIMEOUT" in "" ) TIMEOUT="$PREF_TIMEOUT" ;; esac
 case "$TIMEOUT" in ""|*[!0-9]*|0) TIMEOUT=60 ;; esac
 
-command -v claude >/dev/null 2>&1 || degrade "the claude CLI is not on PATH"
+FALLBACK_MODEL="${PREF_MODEL:-haiku}"
+[ "$FALLBACK_MODEL" = "free" ] && FALLBACK_MODEL="haiku"
+[ "$MODEL" = "free" ] || command -v claude >/dev/null 2>&1 || degrade "the claude CLI is not on PATH"
 
 LINES=$(wc -l < "$FILE" | tr -d ' ')
 BYTES=$(wc -c < "$FILE" | tr -d ' ')
@@ -163,7 +166,8 @@ fi
 
 PROMPT_FILE="$(mktemp -t bulk-read.XXXXXX)"
 OUT_FILE="$(mktemp -t bulk-read-out.XXXXXX)"
-trap 'rm -f "$PROMPT_FILE" "$OUT_FILE"' EXIT
+FREE_DIR="$(mktemp -d -t bulk-read-free.XXXXXX)"
+trap 'rm -rf "$PROMPT_FILE" "$OUT_FILE" "$FREE_DIR"' EXIT
 
 # The worker gets numbered lines because every claim it makes has to be
 # addressable afterwards. `nl -ba` numbers blank lines too, so the numbers match
@@ -191,6 +195,90 @@ done
 } > "$PROMPT_FILE"
 
 START=$(date +%s)
+TIMEOUT_BIN=""
+for candidate in timeout gtimeout; do
+  command -v "$candidate" >/dev/null 2>&1 && { TIMEOUT_BIN="$candidate"; break; }
+done
+
+# The free chain gets the same persona, question and numbered lines, and the
+# bulk-reader output schema. The toolkit verifies the answer
+# against the numbered text before it returns it; the range check below adds
+# what only this script knows, the file's line count. Anything short of a
+# verified, in-range answer hands the read to the Anthropic default.
+FREE_DONE=0
+if [ "$MODEL" = "free" ]; then
+  FREE_REASON=""
+  _MA_TL="$(dirname "${BASH_SOURCE[0]}")/../lib/toolkit-llm.sh"
+  [ -f "$_MA_TL" ] || _MA_TL="$HOME/.claude/lib/toolkit-llm.sh"
+  FREE_SCHEMA="$HERE/../schemas/bulk-read-output.schema.json"
+  if [ -f "$_MA_TL" ] && [ -f "$FREE_SCHEMA" ]; then
+    . "$_MA_TL"
+    # The sandbox of an unattended run denies writes under ~/.claude, where the
+    # toolkit keeps its quota and usage files by default.
+    if [ "${MULTI_AGENT_UNATTENDED:-}" = "1" ] && [ -z "${MCP_TOOLKIT_INDEX_DIR:-}" ]; then
+      export MCP_TOOLKIT_INDEX_DIR="$HOME/.multi-agent-unattended/toolkit-index"
+    fi
+    nl -ba "$FILE" > "$FREE_DIR/numbered.txt"
+    FREE_PROMPT="$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$PERSONA")
+<question>
+$QUESTION
+</question>
+The SOURCE is the file $FILE with its $LINES lines numbered."
+    ALLOW_FLAG=""
+    for prefs in "${MULTI_AGENT_PREFS:-}" "$HOME/.claude/multi-agent-preferences.json" "$HOME/.config/multi-agent-pipeline/multi-agent-preferences.json"; do
+      [ -n "$prefs" ] && [ -f "$prefs" ] || continue
+      [ "$(jq -r '.global.modelRouting.free.allowTraining // false' "$prefs" 2>/dev/null)" = "true" ] && ALLOW_FLAG="--allow-training"
+      break
+    done
+    if [ -n "$TIMEOUT_BIN" ]; then
+      "$TIMEOUT_BIN" "$TIMEOUT" bash -c '. "$1"; shift; ma_toolkit_llm "$@"' _ "$_MA_TL" delegate --task summarize \
+        --prompt "$FREE_PROMPT" --path "$FREE_DIR/numbered.txt" --schema "$FREE_SCHEMA" \
+        --max-tokens 2048 $ALLOW_FLAG > "$FREE_DIR/result.json" 2>/dev/null
+    else
+      ma_toolkit_llm delegate --task summarize --prompt "$FREE_PROMPT" --path "$FREE_DIR/numbered.txt" \
+        --schema "$FREE_SCHEMA" --max-tokens 2048 $ALLOW_FLAG > "$FREE_DIR/result.json" 2>/dev/null
+    fi
+    FREE_STATUS=$?
+    case "$FREE_STATUS" in
+      0)
+        if LINES="$LINES" python3 - "$FREE_DIR/result.json" "$OUT_FILE" <<'PYEOF'
+import json, os, sys
+r = json.load(open(sys.argv[1]))
+v = r.get("value")
+n = int(os.environ["LINES"])
+ok = isinstance(v, dict)
+for reg in (v or {}).get("regions") or []:
+    ok = ok and 1 <= reg.get("start", 0) <= reg.get("end", 0) <= n
+for sym in (v or {}).get("symbols") or []:
+    ok = ok and 1 <= sym.get("line", 0) <= n
+if not ok:
+    sys.exit(1)
+json.dump(v, open(sys.argv[2], "w"))
+open(sys.argv[2] + ".via", "w").write("free:%s/%s" % (r.get("provider"), r.get("model")))
+PYEOF
+        then
+          FREE_DONE=1
+          MODEL=$(cat "$OUT_FILE.via"); rm -f "$OUT_FILE.via"
+        else
+          FREE_REASON="the free answer cited lines outside 1-$LINES"
+        fi ;;
+      3) FREE_REASON="no free provider produced a verified answer" ;;
+      124) FREE_REASON="the free chain did not answer within ${TIMEOUT}s" ;;
+      *) FREE_REASON="the free chain is unavailable (exit $FREE_STATUS)" ;;
+    esac
+  else
+    FREE_REASON="toolkit-llm.sh or the bulk-read output schema is not installed"
+  fi
+  [ -x "$HERE/log-metric.sh" ] && \
+    "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.free \
+      outcome="$([ "$FREE_DONE" = 1 ] && echo verified || echo escalated)" reason="${FREE_REASON:-ok}" >/dev/null 2>&1
+  if [ "$FREE_DONE" != 1 ]; then
+    echo "bulk-read: free chain not used ($FREE_REASON); reading on $FALLBACK_MODEL" >&2
+    MODEL="$FALLBACK_MODEL"
+    command -v claude >/dev/null 2>&1 || degrade "the claude CLI is not on PATH"
+  fi
+fi
+
 # `claude -p` reads the prompt from stdin; the model flag names the rung. A
 # non-zero exit, an empty answer and a non-JSON answer are all degradations, and
 # each one names itself rather than falling through to a generic failure.
@@ -198,11 +286,9 @@ START=$(date +%s)
 # GNU spelling would leave the budget silently unenforced on the platform most of
 # these runs happen on - a pref that does nothing, which is the class
 # smoke-prefs-consumed exists to catch.
-TIMEOUT_BIN=""
-for candidate in timeout gtimeout; do
-  command -v "$candidate" >/dev/null 2>&1 && { TIMEOUT_BIN="$candidate"; break; }
-done
-if [ -n "$TIMEOUT_BIN" ]; then
+if [ "$FREE_DONE" = 1 ]; then
+  STATUS=0
+elif [ -n "$TIMEOUT_BIN" ]; then
   "$TIMEOUT_BIN" "$TIMEOUT" claude -p --model "$MODEL" < "$PROMPT_FILE" > "$OUT_FILE" 2>/dev/null
   STATUS=$?
 else

package/pipeline/scripts/cost-table.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Per-model unit prices in USD per million tokens. Source: Anthropic public pricing (Claude-family rows verified 2026-07-28 against the current model table; the gpt-* rows remain approximate). Update when Anthropic publishes new tiers. Rung names (fable / opus / sonnet / haiku) are the pipeline's stable identifiers and `modelId` is the wire value they currently resolve to - dispatch reads the rung, so a generation move is a `modelId` edit here plus the phase specs, never a rename of the rungs. `provider` says which layer a rung belongs to: an `anthropic` rung is reachable from every call site, a non-anthropic one only from the call sites the pipeline makes itself (bulk-read, research), which is what model-dispatch.sh enforces. Unknown models render USD as ' - ' and emit a footnote  -  never block PR-body generation. cacheReadPerMtok is the discounted rate for prompt-cache hits (~10% of inPerMtok); the renderer prices a phase's tokens_cached at this rate when the tracker records it, so resume/cache reuse is visible in the ledger.",
+  "_readme": "Per-model unit prices in USD per million tokens. Source: Anthropic public pricing (Claude-family rows verified 2026-07-28 against the current model table; the gpt-* rows remain approximate). Update when Anthropic publishes new tiers. Rung names (fable / opus / sonnet / haiku) are the pipeline's stable identifiers and `modelId` is the wire value they currently resolve to - dispatch reads the rung, so a generation move is a `modelId` edit here plus the phase specs, never a rename of the rungs. `provider` says which layer a rung belongs to: an `anthropic` rung is reachable from every call site; `free-chain` (the `free` rung) only from bulk-read and delegate, where the multi-agent-toolkit's verified free-model chain answers and the caller's default takes over when it escalates; any other provider from no call site. model-dispatch.sh enforces this. Unknown models render USD as ' - ' and emit a footnote  -  never block PR-body generation. cacheReadPerMtok is the discounted rate for prompt-cache hits (~10% of inPerMtok); the renderer prices a phase's tokens_cached at this rate when the tracker records it, so resume/cache reuse is visible in the ledger.",
   "schemaVersion": "1.1.0",
   "prices": {
     "fable": {
@@ -57,6 +57,14 @@
       "modelId": "gpt-5.6-terra",
       "provider": "openai",
       "note": "Codex CLI floor tier  -  speed-optimised, maps the haiku rung of the Codex persona tier map (task-clarifier). Approximate; verify against OpenAI pricing before relying on totals."
+    },
+    "free": {
+      "inPerMtok": 0.0,
+      "outPerMtok": 0.0,
+      "cacheReadPerMtok": 0.0,
+      "modelId": "free-chain",
+      "provider": "free-chain",
+      "note": "Layer 2: the multi-agent-toolkit's verified free-model chain (llm_delegate / multi-agent-toolkit-llm) over free tiers - Groq, Mistral, Gemini, OpenRouter free models, Z.AI GLM Flash, local Ollama. Priced at zero because the provider bills nothing on a free tier; what it saves is reported by route-status from the toolkit's usage log at the rate of the rung it replaced."
     }
   }
 }

package/pipeline/scripts/doctor.mjs

@@ -104,6 +104,7 @@ const CHECK_IDS = [
   "disk-space",
   "worktree-residue",
   "usage-report",
+  "free-models",
   "xcode-skills",
 ];
 
@@ -935,6 +936,104 @@ function checkUsageReport() {
   );
 }
 
+// route-on --free promises that simple tasks leave Claude. With no usable
+// provider every one of them silently escalates back, which costs nothing but
+// saves nothing either - the user believes a control is working that is not.
+// --probe sends each configured provider one tiny request, so a dead key or an
+// exhausted quota shows up here instead of as a week of escalations.
+function checkFreeModels() {
+  const prefs = readJson(join(CLAUDE, "multi-agent-preferences.json"));
+  const routing = prefs?.global?.modelRouting;
+  if (routing?.enabled !== true || routing?.free?.enabled !== true) {
+    skip("free-models", "free-model routing is off");
+    return;
+  }
+  const lib = [
+    join(HERE, "..", "lib", "toolkit-llm.sh"),
+    join(CLAUDE, "lib", "toolkit-llm.sh"),
+  ].find((p) => existsSync(p));
+  if (!lib) {
+    report(
+      "free-models",
+      "WARN",
+      "route-on --free is on but lib/toolkit-llm.sh is not installed, so every free task escalates to Claude",
+      `run ${hostCommand("update", HERE)}`,
+    );
+    return;
+  }
+  const train = routing.free.allowTraining === true ? ["--allow-training"] : [];
+  const run = (args) =>
+    JSON.parse(
+      execFileSync("bash", ["-c", '. "$1"; shift; ma_toolkit_llm "$@"', "_", lib, ...args], {
+        encoding: "utf8",
+        timeout: PROBE ? 180000 : 60000,
+        stdio: ["ignore", "pipe", "ignore"],
+      }),
+    );
+  let listing;
+  try {
+    listing = run(["providers", ...train]);
+  } catch {
+    report(
+      "free-models",
+      "WARN",
+      "route-on --free is on but the multi-agent-toolkit CLI could not be run (node and npx are needed), so every free task escalates to Claude",
+      "run npx -y --@mmerterden:registry=https://registry.npmjs.org -p @mmerterden/multi-agent-toolkit-mcp@latest multi-agent-toolkit-llm providers",
+    );
+    return;
+  }
+  const usable = (listing.providers || []).filter((p) => p.configured && p.allowed_by_policy);
+  const detail = (listing.providers || []).map(
+    (p) =>
+      `${p.id}: ${p.configured ? (p.allowed_by_policy ? `ready (${p.key_source})` : `configured, outside the ${listing.data_policy} policy`) : `missing - ${p.setup}`}`,
+  );
+  if (!usable.length) {
+    report(
+      "free-models",
+      "WARN",
+      `route-on --free is on but no free provider is usable under the ${listing.data_policy} data policy, so every free task escalates to Claude`,
+      'run bash "$HOME/.claude/lib/credential-store.sh" set llm-groq - and paste a free key from https://console.groq.com/keys',
+      detail,
+    );
+    return;
+  }
+  if (!PROBE) {
+    report("free-models", "OK", null, null, detail);
+    return;
+  }
+  let probed;
+  try {
+    probed = run(["probe"]);
+  } catch {
+    report(
+      "free-models",
+      "WARN",
+      "the free-provider probe could not run",
+      "re-run with --probe once the network is reachable",
+      detail,
+    );
+    return;
+  }
+  const dead = probed.filter((r) => usable.some((u) => u.id === r.provider) && r.outcome !== "ok");
+  if (dead.length === usable.length) {
+    report(
+      "free-models",
+      "WARN",
+      `every usable free provider failed a probe (${dead.map((r) => `${r.provider}: ${r.outcome}`).join(", ")}), so free tasks escalate to Claude until one recovers`,
+      "set a fresh key for the failing provider with the credential store, or add a second provider",
+      probed.map((r) => `${r.provider}: ${r.outcome}${r.reason ? ` (${r.reason})` : ""}`),
+    );
+    return;
+  }
+  report(
+    "free-models",
+    "OK",
+    null,
+    null,
+    probed.map((r) => `${r.provider}: ${r.outcome}${r.reason ? ` (${r.reason})` : ""}`),
+  );
+}
+
 // Apple's Xcode skills are the reference for iPhone Duo and window resizing,
 // SwiftUI, App Intents and the accessibility audits, and Claude Code reads them
 // from a copy the installer keeps at the installed Xcode build. A newer Xcode
@@ -1263,6 +1362,7 @@ function main() {
   checkDiskSpace();
   checkWorktreeResidue();
   checkUsageReport();
+  checkFreeModels();
   checkXcodeSkills();
   if (PROFILE === "server") checkServerProfile(resolved);
 

package/pipeline/scripts/pre-commit-check.sh

@@ -227,7 +227,7 @@ $folded"
 
   # Model-provider and ML-hub keys. `sk-ant-` and `sk-proj-` are checked before
   # the bare `sk-` form so the message names the provider a reader can revoke.
-  if echo "$content" | grep -qE 'sk-ant-[A-Za-z0-9_-]{32,}|sk-proj-[A-Za-z0-9_-]{32,}|pplx-[A-Za-z0-9]{32,}|hf_[A-Za-z0-9]{30,}'; then
+  if echo "$content" | grep -qE 'sk-ant-[A-Za-z0-9_-]{32,}|sk-proj-[A-Za-z0-9_-]{32,}|sk-or-v1-[A-Za-z0-9]{40,}|pplx-[A-Za-z0-9]{32,}|hf_[A-Za-z0-9]{30,}|gsk_[A-Za-z0-9]{40,}'; then
     echo "BLOCKED: Model-provider API key in $file" >&2
     FOUND=1
   fi

package/pipeline/scripts/unattended_policy.py

@@ -2644,6 +2644,24 @@ def _toolkit_path_refusal(name, ti, policy, env, cwd):
     return None
 
 
+def _free_routing_on(env):
+    """modelRouting.enabled and modelRouting.free.enabled in the preferences
+    file. The user's own switch, read at call time: off, unreadable or absent
+    all mean off."""
+    env = env if env is not None else os.environ
+    home = env.get("HOME") or os.path.expanduser("~")
+    for path in (env.get("MULTI_AGENT_PREFS"), os.path.join(home, ".claude", "multi-agent-preferences.json")):
+        if not path or not os.path.isfile(path):
+            continue
+        try:
+            with open(path, encoding="utf-8") as fh:
+                routing = (json.load(fh).get("global") or {}).get("modelRouting") or {}
+        except (OSError, ValueError, AttributeError):
+            return False
+        return routing.get("enabled") is True and (routing.get("free") or {}).get("enabled") is True
+    return False
+
+
 def check_toolkit(name, ti, policy, env, depth=0, cwd=None):
     """A multi-agent-toolkit tool call, by its short name (web_goto,
     ios_open_url, agent_run_steps). agent_run_steps dispatches other toolkit
@@ -2653,6 +2671,8 @@ def check_toolkit(name, ti, policy, env, depth=0, cwd=None):
         return f"{name} arguments are not an object the guard can read"
     if name.startswith("research_"):
         return f"{name} sends the query to an outside service"
+    if name == "llm_delegate" and not _free_routing_on(env):
+        return "llm_delegate sends text to a free-model provider; unattended runs allow it only after route-on --free"
     if name == "web_eval":
         return "web_eval runs arbitrary JavaScript that can reach any host; refused unattended"
     if name == "agent_run_steps":

package/pipeline/skills/.skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-11T20:10:05Z",
+  "generatedAt": "2026-10-12T02:17:06Z",
   "skillCount": 228,
   "entries": [
     {
@@ -173,11 +173,11 @@
     },
     {
       "path": "shared/core/multi-agent-route-on/SKILL.md",
-      "sha256": "a807767460b09455087d48a7dd45036be788f67997475360acab29f2422f425b"
+      "sha256": "97c76d711454e6bc9edfd47344bbeab7f73cf72c116cca92cffacdcda7fe96b1"
     },
     {
       "path": "shared/core/multi-agent-route-status/SKILL.md",
-      "sha256": "b473b670b3f8535b295752eb5aed8b01cba8d1ed6763ae4d80d9cc2dbb1f7794"
+      "sha256": "869689dbf84edece67168a892a61b51459ff6c15cbf7dafe40c2b774f875b9f0"
     },
     {
       "path": "shared/core/multi-agent-routines/SKILL.md",
@@ -213,7 +213,7 @@
     },
     {
       "path": "shared/core/multi-agent-setup/SKILL.md",
-      "sha256": "427df811e5130da1ab6e23ff78202eb9134fb76bcd601924fba5668cbd630158"
+      "sha256": "e3523960d5d178125302e5ceeb865902d7b12ea5d615670cddeb4d542fa48035"
     },
     {
       "path": "shared/core/multi-agent-stack/SKILL.md",
@@ -269,7 +269,7 @@
     },
     {
       "path": "shared/core/multi-agent/SKILL.md",
-      "sha256": "3dd44ccc00e41c09e59ad223900a391f80158bd3f69e45d67c684285bc42418d"
+      "sha256": "a39f712426638e7955db9171c950be720f11c861621884e628c81a0b6a49de5d"
     },
     {
       "path": "shared/external/accessibility-compliance-accessibility-audit/SKILL.md",

package/pipeline/skills/shared/core/multi-agent/SKILL.md

@@ -122,6 +122,8 @@ export CLAUDE_CODE_SUBAGENT_MODEL="$resolved_model"
 
 **Precedence:** per-dispatch `PHASE_MODEL_OVERRIDE` > `prefs.global.modelRouting` rule > persona `preferredModel` > global default (`opus`). Routing here is Anthropic-only: features/model-fallback.md "Routing at dispatch".
 
+**Simple text tasks (`delegate`):** before summarizing a log or document, extracting fields, labelling or drafting a translation or commit body in-session, ask `"$HOME/.claude/lib/model-dispatch.sh" delegate --default host`. `free` means call `llm_delegate`; `ESCALATE_TO_CLAUDE` or any other answer means do it in-session. Never for code, plans, reviews or triage. Task list and rules: `$HOME/.claude/multi-agent-refs/features/free-models.md`.
+
 **Observability:** emit `phase.agent.dispatch` OTel span with `{persona, resolved_model, override_source}` attributes when `MULTI_AGENT_OTEL_SPANS=1` (see `phase-tracker.sh`).
 
 ## Skill loading and injection

package/pipeline/skills/shared/core/multi-agent-route-on/SKILL.md

@@ -2,7 +2,7 @@
 name: multi-agent-route-on
 description: "Enable policy-driven model routing: pick a strategy, a scope, and the rules that say which rung a call lands on. Use when asked to turn model routing on."
 user-invocable: true
-argument-hint: "[--strategy=manual|task-fit|cost-ceiling] [--scope=subagent,bulk-read,research]"
+argument-hint: "[--free [--allow-training] | --no-free] [--strategy=manual|task-fit|cost-ceiling] [--scope=subagent,bulk-read,delegate,research]"
 metadata:
   language: en
 ---
@@ -24,7 +24,8 @@ Routing ships **off**. This is the command that turns it on, and it writes to
 ```
 
 Ordered, first match wins. `when` matches on `persona`, `phase` (0..5) or
-`taskKind`; `prefer` lists rungs in descending preference.
+`taskKind`; `prefer` lists rungs in descending preference. `free` is a rung too,
+honoured only at `bulk-read` and `delegate` and only while `--free` is on.
 
 **Rung names are the contract; model ids are not.** `opus` is a rung here and a
 model id in `cost-table.json`, and the second can change without anyone editing
@@ -37,18 +38,41 @@ Set rules with:
 bash "$HOME/.claude/lib/route-state.sh" set-rules path/to/rules.json
 ```
 
+## Free models: `--free`
+
+```bash
+bash "$HOME/.claude/lib/route-state.sh" on --free
+```
+
+Layer 2. Simple text work the pipeline does itself - a large-file read, a log or
+document summary, field extraction, a label, a translation or commit-body draft -
+goes to the multi-agent-toolkit's verified free-model chain first. Every answer
+is checked against its source before it is used; when none passes, Claude does
+the task as before. Decisions, plans, code, reviews and triage never leave Claude.
+
+`--free` turns on `modelRouting.free`, adds `bulk-read` and `delegate` to the
+scope, and lists which providers are usable. With none, it says exactly which key
+to add: one free Groq key is enough. `--allow-training` also admits free tiers
+that may train on prompts; leave it off for corporate code and tickets.
+`--no-free` turns only the free chain off. Full contract, the task list for
+development and analysis, and unattended behaviour:
+`$HOME/.claude/multi-agent-refs/features/free-models.md`.
+
 ## Strategies
 
 | Strategy | What it does |
 |---|---|
 | `manual` | only the explicit rules apply, nothing is inferred. The default, because a router that guesses is a router nobody can predict |
-| `task-fit` | a rule may match on `taskKind`, and the cheapest rung clearing it is chosen |
-| `cost-ceiling` | rungs downgrade as the run approaches `budgetCeilingUsd` |
+| `task-fit` | the matched rule's rungs are tried cheapest first (cost-table prices, `free` first) |
+| `cost-ceiling` | the rule's order holds until the run reaches the warn threshold of `budgetCeilingUsd`, then the cheapest rung is tried first |
+
+`set-rules` checks every rule against the schema and the cost table and writes
+nothing if one fails: an unknown rung, a phase outside 0-5, an unknown key.
 
 ## Scope, and the value that is not in it
 
 `scope` names the call sites routing may act on: `subagent`, `bulk-read`,
-`research`. Every one of them is a call **this pipeline makes itself**.
+`delegate`, `research`. Every one of them is a call **this pipeline makes itself**.
 
 There is no `host-session` value, and that absence is enforced by that schema
 rather than written as advice. Routing a host session means rewriting the CLI's
@@ -61,8 +85,8 @@ Passing `--scope=host-session` is refused with that reason, not ignored.
 
 On Claude Code a subagent cannot be dispatched to a non-Anthropic model: subagent
 dispatch belongs to the host, not to us. So Phase 1, 2 and 3 personas stay inside
-the Anthropic ladder no matter what the rules say, and external providers apply
-only at `bulk-read` and `research`, where the pipeline makes the HTTP call.
+the Anthropic ladder no matter what the rules say, and the `free` rung applies
+only at `bulk-read` and `delegate`, where the pipeline makes the call itself.
 
 This is printed by `route-status` on every invocation instead of living in a doc,
 because the question it answers - "routing is on, why is the reviewer still on

package/pipeline/skills/shared/core/multi-agent-route-status/SKILL.md

@@ -28,13 +28,23 @@ A disabled router with rules is deliberately not reported as "off" alone: that
 reads as "unconfigured" and sends the user through `route-on`'s questions a
 second time.
 
+## Free models and what they saved
+
+With `route-on --free`, status also prints `free: true` with its data policy,
+where the free chain answers first (`bulk-read`, `delegate`), and the last seven
+days from the toolkit's usage log: tasks answered free and verified, answers
+served from cache, tasks handed back to Claude, and the input and output tokens
+kept off Claude with an estimated saving at haiku rates. The estimate is labelled
+as one: it prices the tokens at the rung the task would otherwise have used.
+
 ## The limit, printed every time
 
 On Claude Code a subagent cannot be sent to a non-Anthropic model. Subagent
 dispatch belongs to the host; the pipeline asks for a persona and the host
 decides what answers. So Phase 1, 2 and 3 personas stay inside the Anthropic
-ladder whatever the rules say, and an external provider is only reachable where
-the pipeline makes the HTTP call itself - `bulk-read.sh` and `research_ask`.
+ladder whatever the rules say, and a free model answers only where the pipeline
+makes the call itself - `bulk-read.sh` and the `delegate` call site - and only
+after the toolkit verified its answer against the source.
 
 This paragraph is output, not documentation, because the alternative is the
 question arriving later as "routing is on but the reviewer is still on Opus, is

package/pipeline/skills/shared/core/multi-agent-setup/SKILL.md

@@ -189,6 +189,7 @@ The Step 2 discovery summary is never the end of setup. Immediately after showin
 10. `jenkins`
 11. App Store Connect block (Step 3b; only when the target repo is iOS)
 12. Google Play block (Step 3d; only when the target repo is Android)
+13. Free-model keys `llm-<id>` (only after `route-on --free`): `$HOME/.claude/multi-agent-refs/setup/free-models.md`
 
 Loop rules: