@mmerterden/multi-agent-pipeline 20.19.0 → 20.21.0

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 |
@@ -231,9 +231,10 @@ allowed host is allowed; `corpDomain` is not used, because it is an email domain
 and would allow every host under it. The host is parsed with
 `urllib.parse.urlsplit`, so `http://evil.com#@github.com/` resolves to `evil.com`
 and is refused. The same allowlist governs `WebFetch`, the toolkit's
-`web_goto` / `web_crawl` (any URL argument), each step of `agent_run_steps`,
+`web_goto` / `web_crawl` / `web_map` / `web_scrape` (any URL argument), each step of `agent_run_steps`,
 and a web URL given to `ios_open_url` / `android_open_url`; `web_eval` is
-refused outright because inline JavaScript can reach any host. Reads only: a request body or
+refused outright because inline JavaScript can reach any host. Every entry of a
+`paths` list (`web_upload`) is held to the same path rules as a single path argument. Reads only: a request body or
 upload - `-d`/`--data*`, `-F`/`--form`, `-T`/`--upload-file`, and their attached
 and clustered short forms (`-d@file`, `-sd`, `-Tfile`) - is **refused outright**,
 whatever the host, rather than allowed to an allowlisted one; a run has nothing
@@ -511,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/refactor/toolkit-research.md

@@ -28,10 +28,12 @@ Loaded on demand by `/multi-agent:refactor` Step 0c. The SKILL.md carries the st
 |---|------|---------------|-----------------|
 | 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
 | 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
-| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
+| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50`; standing watchlist: `microsoft/playwright-mcp` (browser tool surface, capability groups), `firecrawl/firecrawl-mcp-server` (scrape / crawl / map / extract formats). Check each peer's license before reading code: AGPL or unlicensed means the idea only | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
 | 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
 | 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
 
+When the toolkit itself is registered, run the axes through it: `research_ask` with `mode: "pro"` (or `"deep"` for a whole axis) and `recency: "month"` for release-note questions, `research_search` with `provider: "arxiv"` for papers, `web_scrape` with `change_tracking` on a release-notes page to see what moved since the last refactor. WebSearch / WebFetch stay the fallback.
+
 **Audit the toolkit against the findings**  -  run the checks, do not assume:
 
 ```bash

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": [],

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/schemas/unattended-profile.json

@@ -144,7 +144,7 @@
     [
       "MCP_TOOLKIT_URL_POLICY",
       "strict",
-      "web_goto and web_crawl refuse loopback, link-local and metadata addresses"
+      "web_goto, web_crawl, web_map and web_scrape refuse loopback, link-local and metadata addresses"
     ],
     [
       "MCP_TOOLKIT_INDEX_DENY",

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."
     }
   }
 }