agent-composer 0.1.8 → 0.1.10

package/dist/providers/AnthropicCompatibleProvider.d.ts

@@ -31,6 +31,8 @@ export interface AnthropicCreateResult {
     usage: {
         input_tokens: number;
         output_tokens: number;
+        cache_creation_input_tokens?: number;
+        cache_read_input_tokens?: number;
     };
 }
 export interface AnthropicCompatibleProviderOptions {

package/dist/providers/AnthropicCompatibleProvider.js

@@ -63,6 +63,22 @@ export class AnthropicCompatibleProvider {
         if (this.thinking)
             params.thinking = this.thinking;
         const msg = await this.client.messages.create(params);
+        // Best-effort GLM cache-hit telemetry
+        try {
+            const fs = await import("node:fs");
+            const entry = {
+                ts: new Date().toISOString(),
+                model: this.modelLabel,
+                input_tokens: msg.usage.input_tokens,
+                output_tokens: msg.usage.output_tokens,
+                cache_creation_input_tokens: msg.usage.cache_creation_input_tokens ?? 0,
+                cache_read_input_tokens: msg.usage.cache_read_input_tokens ?? 0,
+            };
+            fs.appendFileSync("/tmp/composer-glm-usage.jsonl", JSON.stringify(entry) + "\n");
+        }
+        catch {
+            // best-effort telemetry; never break the provider on log failure
+        }
         const text = msg.content
             .map((b) => (b.type === "text" && typeof b.text === "string" ? b.text : ""))
             .join("");

package/dist/providers/AnthropicCompatibleProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"AnthropicCompatibleProvider.js","sourceRoot":"","sources":["../../src/providers/AnthropicCompatibleProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AnthropicCompatibleProvider.js","sourceRoot":"","sources":["../../src/providers/AnthropicCompatibleProvider.ts"],"names":[],"mappings":"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"}

package/dist/util/brief.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const SliceSchema: z.ZodObject<{
+    file: z.ZodString;
+    startLine: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const BriefSchema: z.ZodObject<{
+    runId: z.ZodString;
+    createdAt: z.ZodString;
+    task: z.ZodString;
+    files: z.ZodArray<z.ZodString>;
+    symbols: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    slices: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        startLine: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Slice = z.infer<typeof SliceSchema>;
+export type Brief = z.infer<typeof BriefSchema>;
+export declare function newBrief(task: string): Brief;
+export declare function writeBrief(brief: Brief, dir?: string): string;

package/dist/util/brief.js

@@ -0,0 +1,37 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+export const SliceSchema = z.object({
+    file: z.string().min(1),
+    startLine: z.number().int().positive().optional(),
+    endLine: z.number().int().positive().optional(),
+    note: z.string().optional(),
+});
+export const BriefSchema = z.object({
+    runId: z.string().uuid(),
+    createdAt: z.string().datetime(),
+    task: z.string().min(1),
+    files: z.array(z.string().min(1)),
+    symbols: z.array(z.string().min(1)).optional(),
+    deps: z.array(z.string().min(1)).optional(),
+    slices: z.array(SliceSchema),
+});
+export function newBrief(task) {
+    return BriefSchema.parse({
+        runId: randomUUID(),
+        createdAt: new Date().toISOString(),
+        task,
+        files: [],
+        slices: [],
+    });
+}
+export function writeBrief(brief, dir = ".composer/briefs") {
+    const validated = BriefSchema.parse(brief);
+    const absDir = resolve(dir);
+    mkdirSync(absDir, { recursive: true });
+    const path = resolve(absDir, `${validated.runId}.json`);
+    writeFileSync(path, JSON.stringify(validated, null, 2), "utf8");
+    return path;
+}
+//# sourceMappingURL=brief.js.map

package/dist/util/brief.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brief.js","sourceRoot":"","sources":["../../src/util/brief.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACjD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACxB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC9C,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC3C,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;CAC7B,CAAC,CAAC;AAKH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,WAAW,CAAC,KAAK,CAAC;QACvB,KAAK,EAAE,UAAU,EAAE;QACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,IAAI;QACJ,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,EAAE;KACX,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAY,EAAE,GAAG,GAAG,kBAAkB;IAC/D,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,KAAK,OAAO,CAAC,CAAC;IACxD,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAChE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-composer",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "description": "Multi-agent orchestration MCP server. Claude orchestrates; GLM and agy do the work.",
   "bin": {

package/plugin/composer-mastermind/agents/coder.md

@@ -18,14 +18,13 @@ You are the Composer **Coder** subagent. Your job is two-step:
    - If GLM returns a unified diff → apply via `Edit` (or multiple `Edit` calls).
    - If GLM returns full file content → use `Write`.
    - If GLM returns a code block targeting a specific location → use `Edit` with the matching `old_string` / `new_string`.
-5. After applying, use `Read` to verify the change landed at the expected lines.
-6. Return a 1-3 sentence summary of what changed (file + line range + intent). DO NOT return GLM's raw output — only the final result.
+5. Return a 1-3 sentence summary of what changed (file + line range + intent). DO NOT return GLM's raw output — only the final result.
 
 # Hard rules
 
 - DO call `composer_code` exactly ONCE per task. If GLM's output is malformed, fail to the orchestrator with a short error.
 - DO apply patches via Edit/Write — that's why those tools are in your list.
-- DO use Read post-edit to verify.
+- DO NOT re-Read after Edit/Write — trust the tool's return value. PostToolUse hooks run lint + tsc as the verification gate. If a real bug shipped, the reviewer subagent catches it on the next pass.
 - DO NOT write code yourself or modify GLM's output beyond mechanical patch application.
 - DO NOT call composer_code more than once — if it fails, return the error.
 - DO NOT use Bash/sed/awk/perl. Edit/Write only.

package/plugin/composer-mastermind/agents/explorer.md

@@ -0,0 +1,51 @@
+---
+name: explorer
+description: Use when the orchestrator needs to map a large repo before dispatching workers. Walks Glob/Grep, writes a typed brief at .composer/briefs/<runId>.json via the Write tool, returns briefPath only — workers consume the brief instead of re-discovering.
+tools: Read, Glob, Grep, Write
+model: haiku
+---
+
+You are the Composer **Explorer** subagent. Your job is to map the relevant slice of the repo, **write a Brief JSON file to disk using the `Write` tool**, and return the path. Workers (coder / researcher / reviewer) consume the brief — they do NOT re-discover.
+
+# Tools you have
+
+`Read`, `Glob`, `Grep`, **`Write`**. The `Write` tool IS available to you. Use it. It is NOT a "composer MCP tool" — it is the standard file-writing tool. The only Write target you are allowed is `.composer/briefs/<runId>.json` (gitignored). Writing the brief is mandatory; returning the JSON in your text reply is NOT a substitute and the orchestrator will reject the dispatch.
+
+# Workflow
+
+1. Receive `{ task }` from the orchestrator.
+2. Use `Glob` and `Grep` to locate the smallest set of files / symbols / dependency edges that touch the task. **Cap at 30 tool calls total.** Stop early if the picture is clear.
+3. Construct a Brief JSON object matching the schema in `src/util/brief.ts`:
+   ```
+   {
+     "runId":     "<v4-uuid>",                       // see UUID rule below
+     "createdAt": "<ISO-8601 with .SSSZ>",
+     "task":      "<orchestrator's task string verbatim>",
+     "files":     ["repo/relative/path.ts", ...],   // deduped
+     "symbols":   ["ExportedName", ...],            // optional
+     "deps":      ["upstream/or/downstream.ts"],    // optional
+     "slices":    [{ "file": "...", "startLine": N, "endLine": M, "note": "..." }]
+   }
+   ```
+4. **Write the brief.** Call the `Write` tool with:
+   - `file_path`: absolute path `<repo>/.composer/briefs/<runId>.json` (use the same absolute prefix you saw in Read results)
+   - `content`: `JSON.stringify(brief, null, 2)` shape — 2-space indented JSON, trailing newline OK
+5. Return ONLY `{ briefPath, fileCount, sliceCount, summary }`. `summary` is 1-3 sentences: shape of the work, what's NOT in scope. Do NOT echo file contents in the summary. Do NOT paste the brief JSON in your reply — the orchestrator already has the path.
+
+# UUID rule (strict)
+
+`runId` MUST match `^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$` — lowercase hex only. Examples (use as templates, vary the digits):
+- `f47ac10b-58cc-4372-a567-0e02b2c3d479`
+- `3c8d2a4f-91e7-45ba-8c3b-5f6d7e9a1b2c`
+
+Non-hex characters (`g`-`z`) WILL fail `BriefSchema.parse` and the orchestrator will reject the brief. If unsure, pick characters strictly from `0123456789abcdef`.
+
+# Hard rules
+
+- DO use the `Write` tool to persist the brief. NOT writing the file is a dispatch failure.
+- DO refuse with a short error if fewer than 10 files match the task — that's an inline-dispatch case. Tell the orchestrator to dispatch inline instead.
+- DO NOT call any `mcp__composer__*` tool. You are pure discovery — the composer MCP tools are for coder/researcher/reviewer.
+- DO NOT write or edit any file except `.composer/briefs/<runId>.json`.
+- DO NOT run Bash.
+- DO NOT return raw matches or file contents in the summary. Return the brief path; the worker reads the brief.
+- DO NOT exceed 30 Glob+Grep calls. If still unclear, write a partial brief and flag the gap in `summary`.

package/plugin/composer-mastermind/hooks/boundary_guard.sh

@@ -1,57 +1,71 @@
 #!/usr/bin/env bash
-# Composer boundary enforcement (PreToolUse hook) — pragmatic profile for
-# daily dev in arbitrary projects.
-#
-# Behaviour:
-#   - Denies Edit/Write/NotebookEdit on the main thread → forces dispatch via
-#     Task(subagent_type="coder") so GLM does code changes.
-#   - Allows Bash on the main thread (light shell ops stay inline).
-#   - Allows Edit/Write inside a subagent — that is how `coder` applies the
-#     patch composer_code returned. Detection covers three field-name shapes
-#     Claude Code has emitted across versions: transcript_path containing
-#     "/subagents/", agent_id/agentId set, is_sidechain/isSidechain true.
-#   - Wraps the deny decision in {"hookSpecificOutput":{...}} as Claude Code
-#     v2.1.150 requires; top-level fields parse cleanly but are ignored.
-#
-# Disable per-session with: COMPOSER_DANGEROUSLY_BYPASS_PERMISSIONS=1 claude
+# Wave 1 F1.5 — Composer boundary enforcement (PreToolUse hook).
+# Contract per docs/adr/0001-contracts.md §C0.4:
+#   stdin:  Anthropic PreToolUse JSON
+#   stdout: optional {"permissionDecision":"deny"|"allow"|"ask", ...}
+#   exit:   always 0; semantics carried by JSON
+# Fail-closed: any unexpected condition (missing jq / empty stdin /
+# malformed JSON / absent tool_name) MUST emit a deny payload.
 
 set -u
 
 emit_deny() {
   local reason="$1"
+  # Claude Code v2.1.150+ requires the decision wrapped in hookSpecificOutput.
+  # Top-level {hookEventName,permissionDecision,permissionDecisionReason} is
+  # parsed without error but silently ignored — Edit/Write succeed anyway.
   jq -nc --arg r "$reason" \
     '{hookSpecificOutput:{hookEventName:"PreToolUse", permissionDecision:"deny", permissionDecisionReason:$r}}' 2>/dev/null \
     || printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
   exit 0
 }
 
+# 1. Dependency: jq is mandatory for safe JSON parsing.
 if ! command -v jq >/dev/null 2>&1; then
+  # Cannot use emit_deny (depends on jq); inline fallback.
   printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"boundary_guard: jq missing, failing closed"}}\n'
   exit 0
 fi
 
+# 2. Read tool-call JSON from stdin.
 INPUT="$(cat || true)"
 if [[ -z "$INPUT" ]]; then
   emit_deny "boundary_guard: empty stdin, failing closed"
 fi
 
+# 3. Parse tool_name. jq surfaces parse errors to stderr (suppressed) and
+#    returns empty on missing/null — both treated as malformed.
 TOOL="$(jq -r '.tool_name // empty' <<<"$INPUT" 2>/dev/null)"
 if [[ -z "$TOOL" ]]; then
   emit_deny "boundary_guard: malformed JSON or missing tool_name, failing closed"
 fi
 
+# 3.5. COMPOSER_DANGEROUSLY_BYPASS_PERMISSIONS (dev-only escape hatch).
+#   When env var equals "1" or "true", allow every tool. Stderr-warns on
+#   every invocation so the bypass is visible in transcripts. Intended
+#   for bootstrap / dev sessions only. NEVER set in CI or runtime.
+#   See ADR 0001 amendment (2026-05-23, Wave-3 Step 1).
 BYPASS="${COMPOSER_DANGEROUSLY_BYPASS_PERMISSIONS:-}"
 if [[ "$BYPASS" == "1" || "$BYPASS" == "true" ]]; then
   printf 'WARN boundary_guard: COMPOSER_DANGEROUSLY_BYPASS_PERMISSIONS=%s — boundary disabled, dev mode only\n' "$BYPASS" >&2
   exit 0
 fi
 
+# 3.6. STOP_EVOLVE killswitch.
+#   If sentinel file exists AND the tool is a composer dispatch, deny.
+#   Sentinel path overridable via COMPOSER_STOP_EVOLVE_FILE (tests use
+#   a temp file); default "$CLAUDE_PROJECT_DIR/STOP_EVOLVE", falling
+#   back to "./STOP_EVOLVE" when CLAUDE_PROJECT_DIR is unset.
 STOP_FILE="${COMPOSER_STOP_EVOLVE_FILE:-${CLAUDE_PROJECT_DIR:-.}/STOP_EVOLVE}"
 if [[ -e "$STOP_FILE" ]] && [[ "$TOOL" == mcp__composer__* ]]; then
   emit_deny "STOP_EVOLVE sentinel present at $STOP_FILE — Composer dispatches paused."
 fi
 
-# Subagent context bypass — coder must Edit/Write to apply GLM's patch.
+# 3.7. Subagent context bypass.
+#   Composer's coder subagent must Edit/Write to apply GLM's patch output.
+#   The hook fires identically for main-thread and subagent calls — without
+#   this carve-out the apply step is impossible. Detect subagent via the
+#   three field-name shapes Claude Code has emitted across recent versions.
 TRANSCRIPT="$(jq -r '.transcript_path // empty' <<<"$INPUT" 2>/dev/null)"
 AGENT_ID="$(jq -r '.agent_id // .agentId // empty' <<<"$INPUT" 2>/dev/null)"
 SIDECHAIN="$(jq -r '.is_sidechain // .isSidechain // empty' <<<"$INPUT" 2>/dev/null)"
@@ -61,12 +75,15 @@ if [[ "$TRANSCRIPT" == */subagents/* ]] \
   exit 0
 fi
 
+# 4. Block list — native dangerous tools + MCP-prefixed variants.
 case "$TOOL" in
-  Edit|Write|NotebookEdit \
-  | mcp__*__write_file | mcp__*__edit_file \
-  | mcp__*__write | mcp__*__edit)
+  Bash|Edit|Write|NotebookEdit \
+  | mcp__*__write_file | mcp__*__edit_file | mcp__*__bash \
+  | mcp__*__write | mcp__*__edit | mcp__*__exec)
     emit_deny "DENY: dispatch Task(subagent_type=\"coder\"); no Bash workaround."
     ;;
 esac
 
+# 5. Pass-through. Emit nothing — Anthropic treats absent JSON + exit 0
+#    as implicit allow. (Explicit allow JSON is also valid but noisier.)
 exit 0

package/plugin/composer-mastermind/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "composer-mastermind",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Multi-agent orchestrator: Claude as brain, GLM/agy as executors. Dispatches code/research/review work to subagents wired through the @composer-mcp/server MCP server.",
   "claudeCodeVersion": ">=4.6",
   "requires": [
@@ -23,7 +23,8 @@
   "agents": [
     "agents/coder.md",
     "agents/researcher.md",
-    "agents/reviewer.md"
+    "agents/reviewer.md",
+    "agents/explorer.md"
   ],
   "commands": [
     "commands/evolve.md"

package/plugin/composer-mastermind/skills/composer-mastermind/SKILL.md

@@ -51,6 +51,35 @@ pinned. For tiny clarifications / refusals / one-line answers,
 multi-step refactors) is where dispatch pays. Trust your
 expected-output estimate; if under 5 lines, just answer.
 
+**Fan-out cap:** Max 3 parallel worker dispatches per turn for repos with >500 source files. Beyond 3, the prompt-cache misses compound faster than the parallelism saves wall time. If file slices overlap across workers, dispatch SEQUENTIALLY — parallel workers on the same files duplicate every Read.
+
+# Explorer protocol (large-repo dispatches)
+
+For repos with >500 source files (or any unfamiliar codebase), prefer an
+**explorer → workers** shape over re-greping in the main session before
+every dispatch. Re-discovery is the single biggest token bleed in this
+architecture: each fresh worker boots without prompt-cache hits and
+re-Reads the same files.
+
+Dispatch shape:
+
+| Situation | Dispatch |
+|---|---|
+| Small repo, files already pinned in conversation | **Inline** — call worker directly with `{ prompt, context }` |
+| Large repo, single worker | `explorer` → consume `briefPath` → ONE worker dispatch with `{ briefPath, task }` |
+| Large repo, multiple workers | `explorer` ONCE → fan out workers, each consumes the **same** `briefPath` |
+
+`briefPath` convention: explorer writes `.composer/briefs/<runId>.json`
+(zod schema in `src/util/brief.ts`). Workers re-validate with
+`BriefSchema.parse(readFileSync(briefPath))` before touching files. The
+brief is the shared cache prefix — passing the same path to N siblings
+is what keeps prompt-cache warm across the fan-out.
+
+**When to skip the explorer:** orchestrator already knows the exact
+file:line targets (e.g. user said "edit src/foo.ts line 42") OR the
+expected worker output is <500 tokens. The explorer dispatch costs
+~1.5k cache tokens itself; don't pay that for an inline-sized task.
+
 # Spend authorization
 
 Read `composer.config.json` `spendAuthorization.mode` before any
@@ -69,6 +98,31 @@ dispatch that hits a real-money provider (`anthropic`,
 CLI providers (`agy`) are billed separately by the user's own auth
 and do not count toward these caps. Mock providers are always free.
 
+# Headless invocation
+
+When composer-mastermind runs inside a headless `claude -p` (eval harness,
+test runner, CI dispatch, scheduled job, any non-interactive context), prefer
+**Haiku** as the orchestrator model. Build-2 dogfood measurement showed
+-66 % cost vs Opus 4.7 on the orchestrator side, with no quality regression
+on the 3 eval tasks. Workers (GLM / agy) are unchanged.
+
+How to invoke:
+
+```sh
+claude -p --model claude-haiku-4-5-20251001 \
+  --output-format json --permission-mode bypassPermissions \
+  "<your prompt>"
+```
+
+Rules:
+
+- Interactive sessions (user is watching): default Opus 4.7. Haiku
+  hands off integration nuance the user expects.
+- Headless / scheduled / eval: default Haiku. The orchestrator's job is
+  delegation, not reasoning — Haiku is sufficient for routing + summary.
+- Override when the orchestration plan itself is non-trivial (>3
+  dispatches, cross-file integration). Then Opus 4.7 earns its keep.
+
 # Token discipline
 
 - You hold context, plans, and integration. Workers hold execution.