@zhixuan92/multi-model-agent 5.0.2 → 5.0.3

package/dist/skills/mma-retry/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: mma-retry
+description: >-
+  Use when a previous mma-* batch returned partial results (some tasks failed or
+  came back incomplete) and you want to re-run JUST the failed indices without
+  re-dispatching the whole batch
+when_to_use: >-
+  A previous mma-delegate / mma-execute-plan / mma-audit / mma-review /
+  mma-debug / mma-investigate batch returned partial results AND you want to
+  re-try the failed indices only. Prefer this over re-dispatching the whole
+  batch or inline-retrying — it's idempotent and preserves the original batch's
+  diagnostics.
+version: 5.0.3
+---
+
+# mma-retry
+
+## Overview
+
+Re-run selected tasks from a completed or failed batch. Specify the original `batchId` and the zero-based indices of the tasks to re-run. The retry runs those tasks fresh with the same configuration as the original batch and produces a new `batchId`.
+
+**Core principle:** A batch is the unit of dispatch, but a TASK is the unit of failure. Retry at the task level so successful tasks aren't re-charged.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Batch returned terminal?" [shape=diamond];
+    "Some tasks failed/incomplete?" [shape=diamond];
+    "All tasks failed?" [shape=diamond];
+    "mma-retry (selected indices)" [shape=box];
+    "Re-dispatch the whole batch" [shape=box];
+    "Investigate first (mma-debug)" [shape=box];
+
+    "Batch returned terminal?" -> "Some tasks failed/incomplete?";
+    "Some tasks failed/incomplete?" -> "All tasks failed?" [label="yes"];
+    "Some tasks failed/incomplete?" -> "Done — read results" [label="no"];
+    "All tasks failed?" -> "Investigate first (mma-debug)" [label="yes"];
+    "All tasks failed?" -> "mma-retry (selected indices)" [label="no — partial"];
+}
+```
+
+**Use when:**
+- A previous batch's terminal envelope shows mixed `completed: true` / `completed: false`
+- 1–N tasks (but not all) need a re-run with the same config
+- You want to keep the original batch's diagnostics intact for comparison
+
+**Don't use when:**
+- All tasks failed → investigate the systemic cause first (`mma-debug`); retrying won't help
+- The original batch is `expired` (TTL elapsed) → re-dispatch fresh
+- You want to change the prompt → re-dispatch with the new prompt; retry preserves the original
+
+## Endpoint
+
+`POST /retry?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+## Request body
+
+```json
+{
+  "batchId": "550e8400-e29b-41d4-a716-446655440000",
+  "taskIndices": [1, 3]
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `batchId` | string (UUID) | yes | Batch ID from a previous dispatch (not yet expired) |
+| `taskIndices` | number[] | yes | Zero-based indices to re-run; must be non-negative integers |
+
+To re-run all tasks: pass `[0, 1, ..., tasks.length - 1]`. (But consider: if all failed, debug instead of retrying.)
+
+## Full example
+
+```bash
+# Original batch had 4 tasks; re-run tasks at index 1 and 3
+BATCH=$(curl -f --show-error -s -X POST \
+  -H "X-MMA-Client: $MMA_CLIENT" \
+  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"batchId":"550e8400-e29b-41d4-a716-446655440000","taskIndices":[1,3]}' \
+  "http://localhost:$PORT/retry?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')   # NEW batchId — not the original
+```
+
+@include _shared/polling.md
+
+## Response shapes
+
+### POST /retry?cwd=<abs> — dispatch response (202)
+
+```json
+{ "batchId": "<uuid>", "statusUrl": "/batch/<uuid>" }
+```
+
+Use `batchId` to poll. `statusUrl` is a convenience pointer. **This is a new batchId** — polling the original batch returns its terminal state.
+
+### GET /batch/:id — polling response
+
+The HTTP status is the state discriminator:
+
+| Status | Meaning |
+|---|---|
+| `202 text/plain` | Still pending — body is the running headline string |
+| `200 application/json` | Terminal — body is the batch envelope below |
+| `404` / `401` / `5xx` | Error — see Error response below; stop polling |
+
+### GET /batch/:id?taskIndex=N — single task slice
+
+Same envelope. `results` contains exactly the task at index `N`. Returns `404 unknown_task_index` if `N` is out of range.
+
+### Reading the task result
+
+Each task result is the per-task wire object (`ComposePayload`):
+
+```json
+{
+  "completed": true,
+  "message": "Task completed; tests passed; one file changed.",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "high",
+      "category": "correctness",
+      "claim": "The function does not handle empty input",
+      "evidence": "function foo() { ... } // no null check",
+      "suggestion": "Add an explicit null guard at the top",
+      "source": "reviewer"
+    }
+  ],
+  "summary": "Refactored utils.ts — removed 3 dead branches, added JSDoc",
+  "filesChanged": ["/project/src/utils.ts"],
+  "commitSha": "abc123def",
+  "blockId": null,
+  "telemetry": {
+    "totalDurationMs": 12400,
+    "totalCostUSD": 0.08,
+    "workerSelfAssessment": "done",
+    "reviewVerdict": "approved",
+    "commitOutcome": "committed",
+    "stopReason": "normal",
+    "haltedStage": null,
+    "stages": [
+      { "name": "prepare",        "outcome": "advance", "durationMs": 2,    "costUSD": 0 },
+      { "name": "register-block", "outcome": "skip",    "comment": "register-block does not apply to route=delegate", "durationMs": 0, "costUSD": 0 },
+      { "name": "implement",      "outcome": "advance", "durationMs": 8900, "costUSD": 0.05 },
+      { "name": "review",         "outcome": "advance", "durationMs": 2100, "costUSD": 0.02 },
+      { "name": "rework",         "outcome": "skip",    "comment": "rework skipped because review approved", "durationMs": 0, "costUSD": 0 },
+      { "name": "commit",         "outcome": "advance", "durationMs": 340,  "costUSD": 0 },
+      { "name": "annotate",       "outcome": "advance", "durationMs": 890,  "costUSD": 0.01 },
+      { "name": "compose",        "outcome": "advance", "durationMs": 68,   "costUSD": 0 },
+      { "name": "terminal",       "outcome": "advance", "durationMs": 100,  "costUSD": 0 }
+    ]
+  }
+}
+```
+
+**Top-level fields to read for the main-agent verdict:**
+
+| Field | When `true` / populated |
+|---|---|
+| `completed: true` | Task succeeded. `message` is the summary; `findings` are post-review issues (if any). |
+| `completed: false` | Task did not complete. `message` names the blocking gate or finding; `findings` carry any discovered issues. |
+| `findings` | Issues surfaced by the worker or reviewer. `severity` = `critical` \| `high` \| `medium` \| `low`. `source` = `implementer` \| `reviewer`. |
+| `filesChanged` | File paths modified (empty for read-only routes). |
+| `commitSha` | Git SHA of the committed diff; `null` for read-only routes or when commit was skipped. |
+| `blockId` | Always `null` (retry replays write tasks; `contextBlockId` is `null` too — no terminal block). |
+
+**The stages array** (always 9 rows) is the canonical telemetry log. `outcome` is one of:
+- `advance` — stage ran and produced its payload
+- `skip` — stage did not run; `comment` explains why
+- `halt` — stage stopped the chain; `comment` is the failure message
+- `not_run` — stage was not reached because a prior stage halted
+
+Use `telemetry.haltedStage` to find the first halt; `telemetry.stopReason` to find why.
+
+### Error response (4xx / 5xx)
+
+```json
+{
+  "error": "<code>",
+  "message": "<human-readable>",
+  "details": { /* optional structured context, e.g. fieldErrors for 400 */ }
+}
+```
+
+`details` is optional and present only when the server has structured additional context.
+
+## Best practices
+
+This skill is one step in the larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-retry`:
+
+- **Recipe C — Investigate-plan-execute (last step).** After `mma-execute-plan` returns mixed results, retry the failed indices to close the loop.
+- **Recipe D — Plan-execute-retry.** Pass the **original `batchId`** as input, specify the failed indices, keep the same configuration. `mma-retry` produces a NEW `batchId` in its response — poll that one for terminal state. Any `contextBlockIds` from the original carry forward.
+
+Anti-pattern alert: **`full-batch-redispatch`** (AP4). Re-dispatching the entire batch re-charges every successful task. Always retry by index.
+
+## Common pitfalls
+
+❌ **Retrying after the batch expired**
+TTL elapsed → original task specs are gone. **Fix:** re-dispatch fresh; the retry endpoint returns 404.
+
+❌ **Retrying without addressing the root cause**
+A flaky task that failed once will likely fail again. **Fix:** investigate (`mma-debug` or read the original `result.error.message`), then retry — or escalate `agentType` to `complex` by re-dispatching.
+
+❌ **Confusing the new and original `batchId`**
+Retry produces a NEW batchId; polling the original returns the old terminal state. **Fix:** save the retry's `batchId` and poll that one.
+
+❌ **Using retry to change task config**
+Retry preserves the ORIGINAL config (prompt, agentType, filePaths, reviewPolicy). **Fix:** if you want different config, re-dispatch with `mma-delegate` / `mma-execute-plan`.
+
+## Terminal context block
+
+Write-route tasks (delegate / execute-plan / retry) do NOT register a terminal context block — their durable record is the commit (`commitSha` + changed files). The per-task result's `contextBlockId` is always `null` for these routes. Read routes (audit / review / debug / investigate / research) return a non-null `contextBlockId`; see those skills for the delta-follow-up recipe.
+
+Note: a re-run **read-route** task registers its own terminal context block (`contextBlockId`); re-run write tasks register none. Original-batch blocks remain intact and are not overwritten.
+
+@include _shared/error-handling.md

package/dist/skills/mma-review/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: mma-review
+description: >-
+  Use when source code needs a quality / security / correctness pass — pre-merge
+  review, post-implementation sanity check, or focused look at a small file set
+  — and the review can run in parallel per file
+when_to_use: >-
+  User asks for a code review or pre-merge check, OR a methodology skill
+  (superpowers:requesting-code-review, /review, /security-review) points at one,
+  AND mmagent is running. Delegate so each file reviews on its own worker; the
+  main agent only decides what to merge. Review on SOURCE CODE — use mma-audit
+  for prose specs / configs.
+version: 5.0.3
+---
+
+# mma-review
+
+## Overview
+
+mma-review is the **pre-merge gate**. Send code files (or a diff) to a worker for structured review against an executability bar: would a maintainer who reads only the verdict and the diff understand which changes are required, why each is required, and where each lives — well enough to apply the fix and re-merge without re-investigating?
+
+Each file is reviewed independently in parallel; results are index-aligned with `filePaths`.
+
+**Core principle:** Reviewer is a different model from the implementer — different training, different blind spots. Cross-model review catches what self-review misses. The reviewer runs against a 10-category failure-mode taxonomy (test gap, cross-file ripple, missing edge case, race, resource leak, backward-compat break, security/performance regression, implicit-contract assumption, pre-existing-bug-vs-new-regression separation) and weighs every change through the security, performance, and correctness lenses regardless of `focus`.
+
+## When to Use
+
+**Use when:**
+- 1+ source code files just changed (post-implementation review)
+- Pre-merge sanity check on a focused diff
+- Security-sensitive code path (`focus: ["security"]`)
+- A specialized review pass (e.g. `focus: ["performance"]` on hot-path code)
+
+**Don't use when:**
+- The thing being reviewed is prose / spec / config → `mma-audit` (better-suited prompt template)
+- You want to know whether a complete branch is mergeable → run `/ultrareview` (multi-model branch review) instead
+- The diff is one-line / one-character → reading inline is faster than dispatch
+
+## How to invoke for cross-file ripple detection
+
+The cross-file ripple pass (changed-symbol → broken caller) only fires when the worker can identify what changed. Two patterns:
+
+- **Diff-as-input (preferred for cross-file ripple)**: pass the diff via the `code` field, plus the named files via `filePaths`. The worker treats the diff as the change-set and greps for callers of changed public symbols.
+- **Files-only (static review)**: pass only `filePaths`. The worker reviews the files in their current state without a change-set, so cross-file ripple is degenerate. Test gap, missing edge case, race, leak, and security/performance findings still fire.
+
+## Endpoint
+
+`POST /review?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+## Request body
+
+```json
+{
+  "code": "inline code snippet (optional if filePaths given)",
+  "focus": ["correctness", "security"],
+  "subtype": "default",
+  "filePaths": ["/project/src/auth/login.ts"],
+  "contextBlockIds": []
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `code` | string | no | Inline code snippet to review |
+| `focus` | string[] | no | Any of `security`, `performance`, `correctness`, `style`. Omit for general review. |
+| `subtype` | `'default'` | no (defaults to `'default'`) | Reserved for future criteria sets; only `default` is wired today. |
+| `filePaths` | string[] | no | Files to review (one worker per file, parallel) |
+| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` — useful for design docs the reviewer should validate against |
+
+Either `code` or `filePaths` (or both) must be provided.
+
+> Worker tier for `mma-review` is hardcoded to `complex` and is not caller-configurable. Sending `agentType` is rejected with HTTP 400.
+
+## Full example
+
+```bash
+BATCH=$(curl -f --show-error -s -X POST \
+  -H "X-MMA-Client: $MMA_CLIENT" \
+  -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"focus":["security","correctness"],"filePaths":["/project/src/auth/login.ts"]}' \
+  "http://localhost:$PORT/review?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+## Reading the findings
+
+The main agent reads `completed` + `message` + `findings` — the findings are the answer. For
+read-only routes, `filesChanged` is always `[]` and `commitSha` is always `null`.
+
+```json
+{
+  "completed": true,
+  "message": "Review complete; 3 findings.",
+  "findings": [
+    { "id": "F1", "severity": "critical", "category": "test-gap",
+      "claim": "login.ts has no test for null username edge case.",
+      "evidence": "Worker read login.ts and grepped for test files — no null-case test found.",
+      "suggestion": "Add test case: `login(null) throws ValidationError`.",
+      "source": "reviewer" }
+  ],
+  "filesChanged": [],
+  "commitSha": null,
+  "summary": "...",
+  "telemetry": { ... }
+}
+```
+
+### Finding shape
+
+Every finding has this shape:
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | string | Worker-assigned, e.g. `F1`, `F2`. Stable across chain. |
+| `severity` | `'critical' \| 'high' \| 'medium' \| 'low'` | 4-tier. |
+| `category` | string | Topical bucket, e.g. `test-gap`, `cross-file-ripple`. |
+| `claim` | string | One-sentence summary. |
+| `evidence` | string ≥20 chars | Verbatim from source when grounded. |
+| `suggestion?` | string | Optional fix recommendation. |
+| `source` | `'implementer' \| 'reviewer'` | Who produced the finding. |
+
+`annotatorConfidence` and `evidenceGrounded` are retired — they were v4 fields with no producers.
+
+### Recommended rendering by the main agent
+
+1. Show ALL findings — never silently drop. Severity and grounding are soft
+   signals, not gates.
+2. Default sort: severity (critical → low), then `id` ascending.
+3. `severity` is the authoritative value — use it directly.
+4. Mark findings with `evidence` shorter than 30 chars as "low-evidence"
+   (lighter color or `(low evidence)` annotation). User decides what to do.
+5. Severity-tier counts feed the dashboard.
+
+## Best practices
+
+This skill is one step in the larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-review`:
+
+- **Recipe A (analog) — Review-iterate-clean.** `mma-review` → fix → `mma-review` again. Same shape as the audit recipe, applied to source code. Sequential rounds; register the file(s) via `mma-context-blocks` before round 1 and reuse the same ID across rounds.
+
+Anti-pattern alert: **`parallel-rounds-same-target`** (AP1). Three parallel reviews of the same source file re-flag the same issues. Run rounds sequentially with a fix between each.
+
+## Common pitfalls
+
+❌ **Reviewing a plan/spec markdown with `mma-review`**
+The reviewer is tuned for code constructs (types, call sites, test coverage). On prose it produces vague nits. **Fix:** use `mma-audit` for docs/specs, `mma-review` for source.
+
+❌ **Omitting `focus` and getting watery findings**
+A general review surfaces low-signal style nits alongside real bugs. **Fix:** specify `focus: ["correctness"]` or `["security"]` to bias the reviewer toward the dimension you care about.
+
+❌ **Inlining the spec the reviewer should validate against**
+If the reviewer needs to check the diff against a design doc, register the doc once via `mma-context-blocks` and pass the `contextBlockIds`. Inlining N times wastes tokens.
+
+❌ **Skipping review because "I already read it"**
+Self-review and cross-model review are not the same thing. The whole reason to delegate is the different blind spots. Read the findings; merge what you agree with.
+
+## Terminal context block
+
+Every completed **read-route** task (audit / review / debug / investigate / research) auto-registers a reusable terminal context block containing its report (headline + findings). The block id is returned on each per-task result as **`contextBlockId`**. Write routes (delegate / execute-plan / retry) return `contextBlockId: null` — their record is the commit, not a block. This block is immutable, lives for the session duration, and counts against the project's `maxEntries` quota (default 500).
+
+Use it for delta follow-ups — feed prior results' block ids into a later call's `contextBlockIds`, filtering out nulls:
+
+    contextBlockIds: priorResults.map(r => r.contextBlockId).filter((id) => id !== null)
+
+**Use cases:**
+- Pass round-N review findings to round N+1 via `contextBlockIds`
+- Feed review results into a downstream `mma-delegate` fix step
+- Accumulate findings across iterative review rounds
+
+The block is registered server-side at task completion; no caller action is needed to create it. Delete it explicitly via `DELETE /context-blocks/:id` when no longer needed, or let it expire on session teardown.
+
+## Outcome semantics
+
+Every task result carries outcome fields that describe the code review's conclusion status:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `findingsOutcome` | `'found' \| 'clean' \| 'not_applicable'` | Answers the question: did the review uncover issues? |
+| `findingsOutcomeReason` | `string \| null` | When `findingsOutcome` is set, this explains why (e.g. "Test gap: login() has no null-username case" or "Code is clean across all review criteria"). |
+| `outcomeInferred` | `boolean` | `true` if the system inferred the outcome from findings count; `false` if the reviewer explicitly stated it. |
+| `outcomeMalformed` | `boolean` | `true` if the outcome line was malformed and had to be repaired; `false` otherwise. |
+
+### Enum values
+
+- **`found`** — the review surfaced one or more issues (findings) across one or more review categories (test gap, cross-file ripple, race, leak, security, performance, etc.). This indicates the code needs rework before merge.
+- **`clean`** — the review completed and found zero issues. The code passes the review bar and is safe to merge.
+- **`not_applicable`** — the review could not proceed (e.g., wrong input type, missing preconditions, or system error). This is rare; most reviews resolve to `found` or `clean`.
+
+### Empty findings ≠ failure
+
+A crucial semantic: **empty findings does NOT mean `completed: false` or a failed review.** Finding nothing wrong is a successful review outcome — it means the code passed inspection. A review with zero findings is `completed: true` with `findingsOutcome: 'clean'`.
+
+### Per-route legal outcomes
+
+The legal outcomes for this route are: `['found', 'clean']`
+
+- **`found`** — one or more issues were detected across the review categories.
+- **`clean`** — zero issues were detected; the code is ready to merge.
+
+The outcome `not_applicable` is not legal for `mma-review` (except on actual precondition failures) because a code review always produces a verdict: either issues found or clean.
+
+@include _shared/error-handling.md

package/dist/skills/multi-model-agent/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: multi-model-agent
+description: >-
+  Use first whenever you're about to delegate any tool-using work — picks the
+  right mma-* skill (audit, review, verify, debug, plan execution, codebase
+  investigation, ad-hoc delegation, retry, context-block reuse) instead of
+  defaulting to inline Agent dispatches
+when_to_use: >-
+  The user asks for work you'd normally delegate — audit, code review, checklist
+  verification, debugging, plan execution, codebase Q&A, or ad-hoc parallel
+  tasks — AND mmagent is running. Read this once, pick the matching mma-* skill,
+  and delegate there. Applies equally whether the user invoked a superpowers
+  methodology skill or asked directly.
+version: 5.0.3
+---
+
+# multi-model-agent (router)
+
+## Overview
+
+Local HTTP service that fans out tool-using work to workers on different LLM providers (Claude, OpenAI-compatible, Codex). Workers run on cheap models; the main agent stays on judgment.
+
+**Core principle:** Pick the most specific `mma-*` skill that fits the task. Specificity reduces input — specialized skills know their route, schema, and defaults so you write less.
+
+## Skill map
+
+```dot
+digraph picker {
+    "Plan/spec file on disk?" [shape=diamond];
+    "Audit a doc?" [shape=diamond];
+    "Review code?" [shape=diamond];
+    "Verify a checklist?" [shape=diamond];
+    "Debug a failure?" [shape=diamond];
+    "Codebase question?" [shape=diamond];
+    "Convergent or divergent?" [shape=diamond];
+    "mma-execute-plan" [shape=box];
+    "mma-audit" [shape=box];
+    "mma-review" [shape=box];
+    "mma-debug" [shape=box];
+    "mma-investigate" [shape=box];
+    "mma-explore" [shape=box];
+    "mma-delegate" [shape=box];
+
+    "Plan/spec file on disk?" -> "mma-execute-plan" [label="yes"];
+    "Plan/spec file on disk?" -> "Audit a doc?" [label="no"];
+    "Audit a doc?" -> "mma-audit" [label="yes"];
+    "Audit a doc?" -> "Review code?" [label="no"];
+    "Review code?" -> "mma-review" [label="yes"];
+    "Review code?" -> "Debug a failure?" [label="no"];
+    "Debug a failure?" -> "mma-debug" [label="yes"];
+    "Debug a failure?" -> "Codebase question?" [label="no"];
+    "Codebase question?" -> "Convergent or divergent?" [label="yes"];
+    "Codebase question?" -> "mma-delegate" [label="no — ad-hoc"];
+    "Convergent or divergent?" -> "mma-investigate" [label="convergent (one answer)"];
+    "Convergent or divergent?" -> "mma-explore" [label="divergent (3-5 directions)"];
+}
+```
+
+| Skill | Purpose |
+|---|---|
+| `mma-execute-plan` | Implement tasks from a plan or spec file (descriptors match plan headings) |
+| `mma-audit` | Audit a document/spec/config for security, correctness, style, or performance |
+| `mma-review` | Review code for quality, security, performance, correctness. Pass acceptance checklists in the brief if you need verification-style checks. |
+| `mma-debug` | Debug a failure with a structured hypothesis |
+| `mma-investigate` | Codebase Q&A — structured answer with `file:line` citations + confidence |
+| `mma-explore` | Divergent ideation from codebase + web research + prior-learnings recall — use before `superpowers:brainstorming` |
+| `mma-delegate` | Ad-hoc implementation / research with no plan file |
+| `mma-retry` | Re-run specific failed/incomplete tasks from a previous batch by index |
+| `mma-context-blocks` | Register a reused doc once; reference by ID across N tasks |
+
+## Best practices
+
+### The unifying principle
+
+The main session is for judgment, orchestration, and dialogue with the engineer. Everything else — read, grep, audit, review, debug, implement, verify — gets delegated. If you're about to do labor in main context, you've already taken the wrong turn.
+
+### Judgment vs labor — what NEVER delegates
+
+Labor handles work whose answer is findable from the inputs. Main session keeps work whose answer is **judgment** — there is no "right answer" a worker could discover:
+
+- **Brainstorming** — exploring the problem space with the engineer before a spec exists.
+- **Spec writing** — deciding what to build, what success looks like, what's out of scope.
+- **Plan writing** — turning a spec into ordered, testable steps with the right decomposition.
+- **Architecture and design decisions** — choosing the shape of the solution.
+- **Final approval / merge decisions** — what ships.
+- **Dialogue with the engineer** — clarifying intent, negotiating tradeoffs, answering "should we?".
+
+The test: *if a worker can produce the answer from the given inputs, delegate; if the answer requires deciding what the inputs should be, it's main-session work.* Recipes A–D all keep these judgment steps in main context (e.g., Recipe C explicitly: `mma-investigate` → **write the plan (main)** → `mma-execute-plan`).
+
+### C1 — Delegate by default, inline by exception
+
+If a task needs 3+ file reads or any grep, it goes to a worker. Inline `Read` is reserved for files already in context, single-file lookups, or 1-2 file reads with a known target.
+
+### C2 — Parallel for independence, sequential for iteration
+
+Independent fan-out (5 unrelated audits, 5 unrelated bugs) → parallel batch. Coupled rounds where round N's fix produces round N+1's input (audit → fix → re-audit, debug → fix → verify) → sequential.
+
+### C3 — Shared content lives in a context block, not in caller tokens
+
+Any artifact (spec, plan, prior-round findings, long error log) that crosses 2+ calls gets registered once via `mma-context-blocks` and referenced by ID.
+
+### Recipe A — Audit-iterate-clean
+
+`mma-audit` → read findings → fix (inline if 1-2 lines, else `mma-delegate`) → `mma-audit` again. Sequential rounds, NOT parallel re-audits. The fix produces new edges; round 2 catches what round 1 couldn't see. Register the doc as a context block before round 1; reuse the same ID across all rounds. The same shape applies to `mma-review` for source code (review → fix → re-review).
+
+### Recipe B — Debug-fix-review
+
+`mma-debug` (read/reproduce/trace) → `mma-delegate` (apply the fix the hypothesis implies) → `mma-review` with the acceptance criteria included in the brief. Three skills, strict order. Register the failing test output / reproduction log as a context block before the debug call; reuse it on the review call so the reviewer can compare against the same evidence.
+
+### Recipe C — Investigate-plan-execute
+
+`mma-investigate` (codebase Q&A) → write the plan (main-context judgment task) → `mma-execute-plan` (workers implement against named plan headings) → `mma-retry` on any failed indices. Register the plan file as a context block before execute-plan; the retry call inherits the same configuration including `contextBlockIds`.
+
+### Recipe D — Plan-execute-retry
+
+When `mma-execute-plan` returns mixed `done` / `done_with_concerns` / `failed`, the next step is `mma-retry` on the failed indices only — never a full-batch re-dispatch. Pass the **original `batchId`** as input, specify the failed task indices, keep the same configuration. (`mma-retry` produces a NEW `batchId` in its response — poll that one for terminal state, not the original.) Any `contextBlockIds` registered for the original batch carry forward into retry — no need to re-register.
+
+### Anti-patterns
+
+1. **`parallel-rounds-same-target`** — Caller fans out 3 parallel calls of the same skill on the same target — `mma-audit` on one document, or `mma-review` on the same source file. The reports overlap heavily; later rounds never see the fix from earlier rounds, so they re-flag the same issues. Corrective: sequential rounds with a fix between each (Recipe A).
+
+2. **`inline-labor-leakage`** — Caller does 3+ `Read` calls, or any `grep`, in main context "just to understand the situation." Main tokens get burned on labor; the answer the caller actually needs is one paragraph of synthesis. Corrective: `mma-investigate` for codebase Q&A; if the goal is implementation, jump straight to `mma-delegate` with file paths and let the worker read.
+
+3. **`re-inlined-shared-content`** — Caller pastes the same spec / plan / error log into 5 task prompts in one batch (or across rounds). Token cost scales linearly with N. Corrective: `mma-context-blocks` register once, pass `contextBlockIds` to every task. C3 fires the moment the same content is referenced a second time.
+
+4. **`full-batch-redispatch`** — Caller re-runs `mma-execute-plan` with the entire task list when only 2 of 8 tasks failed. The 6 successful tasks get re-charged. Corrective: `mma-retry` with the failed indices. (The same anti-pattern applies to multi-task `mma-delegate` batches; `mma-retry` is the corrective there too.)
+
+## Preflight: auto-start the daemon if it is not running
+
+```bash
+PORT=7337
+if ! curl -sf "http://127.0.0.1:$PORT/health" >/dev/null 2>&1; then
+  mmagent serve >/dev/null 2>&1 & disown
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    sleep 0.5
+    curl -sf "http://127.0.0.1:$PORT/health" >/dev/null 2>&1 && break
+  done
+fi
+```
+
+Idempotent: already-running daemon → curl succeeds → no-op. Background `mmagent serve` (with `& disown`) — never run it foreground (it would block the rest of the script).
+
+## Auth token
+
+```bash
+export MMAGENT_AUTH_TOKEN=$(mmagent print-token)
+```
+
+Every request requires `Authorization: Bearer $MMAGENT_AUTH_TOKEN`. The token rotates on every `mmagent serve` restart — re-export after a `pkill`/upgrade.
+
+## Worker tier: `agentType`
+
+Only `mma-delegate` accepts `agentType: "standard" | "complex"` per task — default `"standard"` (cheaper, faster). Pick `"complex"` when:
+
+- The task touches many files or requires multi-step reasoning a standard-tier model cannot hold in context.
+- A prior standard run came back with `filesWritten: 0` or `incompleteReason: "turn_cap"` / `"timeout"`.
+- The task is security-sensitive or ambiguous enough that being wrong is costly.
+
+Every other route hardcodes its tier and rejects `agentType` with HTTP 400:
+
+| Route | Hardcoded tier |
+|---|---|
+| `mma-execute-plan` | `standard` |
+| `mma-audit` | `complex` |
+| `mma-review` | `complex` |
+| `mma-debug` | `complex` |
+| `mma-investigate` | `complex` |
+| `mma-explore` | `complex` (all three workers — internal, external, synthesizer) |
+
+If you need `complex` tier on plan-style work, dispatch via `mma-delegate` with the plan task as the prompt and `agentType: "complex"`.
+
+## Context block defaults
+
+| Default | Value | Notes |
+|---|---|---|
+| Idle TTL | 24 h | Block eligible for eviction after 24 h with no active batch references |
+| `maxEntries` | 500 | Per-project cap on total context blocks |
+| Body cap | 50 MiB | Maximum `content` size per block |
+
+Context blocks are immutable after creation. To update content, register a new block and switch `contextBlockIds` to the new ID.
+
+## Terminal context block
+
+Every completed **read-route** task (audit / review / debug / investigate / research) auto-registers a reusable terminal context block containing its report (headline + findings). The block id is returned on each per-task result as **`contextBlockId`**. Write routes (delegate / execute-plan / retry) return `contextBlockId: null` — their record is the commit, not a block. This block is immutable, lives for the session duration, and counts against the project's `maxEntries` quota (default 500).
+
+Use it for delta follow-ups — feed prior results' block ids into a later call's `contextBlockIds`, filtering out nulls:
+
+    contextBlockIds: priorResults.map(r => r.contextBlockId).filter((id) => id !== null)
+
+## General flow
+
+1. Call the matching `mma-*` skill → receive `{ batchId, statusUrl }`.
+2. Poll `GET /batch/:id`: `202 text/plain` while pending (body is the running headline), `200 application/json` on terminal.
+3. Read `results` / `error` from the 6-field terminal envelope.
+
+## Common pitfalls
+
+❌ **Defaulting to inline Agent dispatch when mmagent is up.** mmagent workers cost ~10× less and don't pollute main context. **Why:** every inline tool call burns flagship-model tokens; that's exactly what mmagent exists to avoid.
+
+❌ **Picking `mma-delegate` when a more specific skill fits.** Audit / review / verify / debug / investigate workers know their route's defaults and emit structured reports. **Why:** specialized skills require less input and produce richer output.
+
+❌ **Starting an investigation that needs to write code.** `mma-investigate` is read-only. **Fix:** dispatch `mma-delegate` with research-then-edit framing, or split: investigate → digest → edit.
+
+## Diagnosing slow tasks
+
+`mmagent serve --verbose` (or `diagnostics.verbose: true` in config) records `tool_call`, `turn_complete`, and `heartbeat` events. Tail with `mmagent logs --follow --batch=$BATCH_ID`.

package/dist/telemetry/consent.d.ts

@@ -0,0 +1,4 @@
+import { type ConsentDecision } from '@zhixuan92/multi-model-agent-core/events/consent-rules';
+export declare function decide(homeDir: string): ConsentDecision;
+export declare function watchConfigForChanges(homeDir: string, onChange: (d: ConsentDecision) => void): () => void;
+//# sourceMappingURL=consent.d.ts.map

package/dist/telemetry/consent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/telemetry/consent.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,wDAAwD,CAAC;AAE7G,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAsBvD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI,CASzG"}