This is a self-contained setup guide for the agent-control half of a long-session\nOpenCode configuration: keeping the context alive across compaction, pushing heavy\nsteps to fresh-context subagents, and keeping the always-on startup prompt small. It\nis one of two companion dumps. The other, The requirements machine, installs the\nREQUIREMENTS.md registry, its coverage check and the idea process; applied\ntogether, the two reproduce the combined context-machine-setup guide.
All files are stripped of the original project's specifics and given in an initial\nempty state — the mechanisms work, domain data is empty. Paths: ~ = the user's home\ndirectory (C:\\Users\\<name> on Windows), <project> = the root of your repository.
The machine solves these problems of long agent sessions:
\nplugins/context-sentinel.ts).plugins/delegate.ts + agents/*.md + DELEGATION MODE protocol).AGENTS.md auto-injected when a file under its path is read), task flows (.opencode/skills/<name>/SKILL.md — only name + description are always-on), and commands (.opencode/command/<name>.md, which force a skill load).set_tier_model with human approval; tiers = appetite for price/intelligence.The fifth problem the original guide names, knowledge drift, is owned by the\ncompanion requirements-machine dump — this dump only keeps the root AGENTS.md\ndigest and STATE.md checkpoint that the registry points into.
Core principles: fail-visible (never stay silent), mechanism not a request (contracts are held by gates and grammar, not by persuasion in the prompt), one truth per entity, verbatim (human instructions are not paraphrased), lazy by default (what is read at startup must not grow).
\n~/.config/opencode/ # GLOBAL LOOP (OpenCode configuration)\n ├── opencode.jsonc # model, plugins, context cap, compaction, permissions\n ├── routing.json # providers + advisor (benchmark feed)\n ├── package.json # plugin dependencies + tests\n ├── README.md # runbook (how to kill what)\n ├── agents/\n │ ├── explore.md # subagent: read-only exploration\n │ ├── worker.md # subagent: coherent implementation step (MAIN)\n │ └── worker-lite.md # subagent: routine (LITE)\n ├── lib/\n │ └── advisor-core.ts # pure advisor helpers (NOT a plugin!)\n ├── plugins/\n │ ├── context-sentinel.ts # compaction + mechanical checkpoint + warnings\n │ ├── delegate.ts # delegate_* / list_models / recommend_model / set_tier_model\n │ └── checkpoint-compaction.ts.disabled # legacy plugin (absorbed by sentinel; do not enable)\n ├── templates/\n │ └── delegation-mode.md # MASTER COPY of the DELEGATION MODE section\n ├── skills/ # LAZY LAYER: task flows\n │ └── <name>/SKILL.md # only name + description are always-on; body on invoke\n ├── command/ # LAZY LAYER: slash-commands\n │ └── <name>.md # thin trigger that forces a skill load ($ARGUMENTS)\n └── tests/\n ├── advisor.test.mjs\n └── context-sentinel.test.mjs\n\n<project>/ # PROJECT LOOP (repository)\n ├── AGENTS.md # agent startup digest (loaded every start)\n ├── REQUIREMENTS.md # ◁ companion dump (requirements machine)\n ├── STATE.md # checkpoint \"what we are doing now\" (untracked)\n ├── .gitignore\n ├── package.json # scripts: test, req, contract, state:diet, workflow-arrows:lint\n ├── .opencode/ # LAZY LAYERS (tracked) + ephemeral checkpoints (ignored)\n │ ├── .gitignore # ignores node_modules/package.json/…; skills & commands stay tracked\n │ ├── skills/<name>/SKILL.md # task flows (only the catalog is always-on)\n │ ├── command/<name>.md # slash-command → skill load\n │ └── CHECKPOINT-*.md # ephemeral compaction checkpoints (gitignored)\n ├── packages/<pkg>/AGENTS.md # optional AREA RULES: auto-injected on read under that path\n ├── scripts/\n │ ├── req-coverage.js # ◁ companion dump (requirements machine)\n │ ├── state-diet.mjs # STATE.md diet (chronicle → archive)\n │ ├── workflow-arrows-lint.mjs # flow map linter (drift → exit 1)\n │ └── contract.mjs # build the code map from module contract-headers\n ├── AGENTS/ # add-ons, read ON DEMAND\n │ ├── README.md # pointer-digest\n │ ├── code-map.md # code map (generated; skeleton here)\n │ ├── workflow-arrows.md # flow map: how to read/lint/render\n │ ├── delegation-mode.md # copy of the master section (enabled by human phrase)\n │ ├── context-machine.md # WHY the context is structured this way\n │ ├── requirements.md # ◁ companion dump (requirements machine)\n │ ├── tools.md # dev-tools protocols\n │ └── domain-model.md # terminology dictionary (two layers)\n └── docs/\n ├── workflow-arrows.puml # machine-readable flow map (empty at start)\n ├── ideas/ # ◁ companion dump (requirements machine)\n │ ├── README.md # idea lifecycle\n │ └── idea-TEMPLATE.md # brainstorm dump template\n └── history/\n └── state.md # STATE.md archive (empty at start)\nThree lazy layers keep the always-on digest small: area rules (a nested AGENTS.md,\nauto-injected on read under its path), task flows (SKILL.md — always-on is only\nname + description), and commands (command/<name>.md, a thin trigger). The project\n.opencode/ holds the tracked lazy layers plus the sentinel's ephemeral checkpoints\n(CHECKPOINT-*.md, gitignored).
~/.config/opencode/, run npm install, run npm test (both tests green).context-sentinel v… loaded; delegate_*, list_models, recommend_model, set_tier_model are available in root).<project>/.<...> placeholders in opencode.jsonc and routing.json with your provider/models (how to check models — runbook §5)..opencode/skills/<name>/SKILL.md for a task flow and .opencode/command/<name>.md to force-load it (see §3.15); a nested packages/<pkg>/AGENTS.md for area rules.REQUIREMENTS.md registry, scripts/req-coverage.js, AGENTS/requirements.md and the docs/ideas/ process.~/.config/opencode/~/.config/opencode/package.json{\n \"type\": \"module\",\n \"scripts\": {\n \"test\": \"node --test\"\n },\n \"dependencies\": {\n \"@opencode-ai/plugin\": \"1.14.19\"\n }\n}\nTests import .ts directly — requires Node ≥ 22.6 (type stripping) or bun.
~/.config/opencode/opencode.jsonc{\n \"$schema\": \"https://opencode.ai/config.json\",\n // Main model for the root session. REPLACE with your verified model.\n \"model\": \"<provider>/<root-model>\",\n // Cheap model for generating titles/summaries (token savings).\n // Must be verified by a real call: \"listed in catalog\" ≠ \"authorized\".\n \"small_model\": \"<provider>/<cheap-model>\",\n \"plugin\": [\n \"./plugins/context-sentinel.ts\",\n // primary-only tools: delegation with model selection + model catalog\n \"./plugins/delegate.ts\"\n ],\n // Effective context budget for the root model.\n // Even if the model supports 1M, cut it to the boundary where quality/latency/price\n // start to degrade (usually 200–250k), so compaction happens where\n // it is still high quality. output < context, so the compaction reserve doesn't exceed the window.\n \"provider\": {\n \"<provider>\": {\n \"models\": {\n \"<root-model>\": {\n \"limit\": { \"context\": 250000, \"output\": 64000 }\n }\n }\n }\n },\n // The last ~30k tokens of the dialogue survive compaction verbatim\n // (protection of exact human instructions) + reserve for the compaction itself.\n \"compaction\": {\n \"auto\": true,\n \"reserved\": 16000,\n \"preserve_recent_tokens\": 30000\n },\n // Delegation tools — only for the root orchestrator;\n // subagents are denied them.\n \"experimental\": {\n \"primary_tools\": [\n \"delegate_simple_task\",\n \"delegate_standard_task\",\n \"delegate_advanced_task\",\n \"list_models\",\n \"recommend_model\",\n \"set_tier_model\"\n ]\n },\n // Money gate, by tiers. Permission in OpenCode is keyed by TOOL NAME,\n // hence one tool per tier. A child always starts with a fresh context\n // (prompt-cache miss) → EVERY delegation costs tokens → by default all are \"ask\".\n // The user can set any tier to \"allow\" (accept forever).\n \"permission\": {\n \"delegate_simple_task\": \"ask\",\n \"delegate_standard_task\": \"ask\",\n \"delegate_advanced_task\": \"ask\",\n \"set_tier_model\": \"ask\"\n }\n }\n~/.config/opencode/routing.json{\n \"providers\": [\"<provider>\"],\n \"advisor\": {\n \"enabled\": true,\n \"reportUrl\": \"https://krivich.github.io/opencode-benchmark/report.json\",\n \"ttlHours\": 24,\n \"maxRows\": 40\n }\n}\nproviders — catalog filter for list_models. advisor — daily benchmark feed: it DOES NOT choose a model and calculates nothing — it only draws a table (model, score, $/session, sessions/mo) along with the baseline (current root model); the root LLM weighs price and intelligence itself and proposes one model for human approval. Feed unavailable/not needed — \"enabled\": false (table degrades to list_models hint).
~/.config/opencode/agents/explore.md---\ndescription: Fast codebase exploration and research (read-only). Use for reading files, searching, and gathering context so the main session saves its token budget.\nmode: subagent\ntemperature: 0.1\nsteps: 15\npermission:\n edit: deny\n write: deny\n---\nYou are a read-only codebase explorer. Your job: find files, read them, search content, and report findings to the parent agent.\n\nRules:\n- NEVER modify files. Research only.\n- Read files in large chunks (2000 lines) instead of tiny slices – fewer requests = more budget.\n- Batch independent tool calls in parallel.\n- NEVER dump entire files into your report. Return compact findings:\n - file paths with line numbers (`src/foo.ts:42`)\n - 2-5 line code snippets only where essential\n - short structured summaries\n- If the task is broad, state what you found AND what you did not find – the parent must not re-search after you.\n- Budget discipline: your context window is 1M. Prefer targeted searches over exhaustive reads.\n\n<!-- managed config: ~/.config/opencode/agents/explore.md (runbook: ~/.config/opencode/README.md §Workers) | disable: mv explore.md{,.disabled} + restart | created <date> -->\n~/.config/opencode/agents/worker.md---\ndescription: Isolated worker, MAIN tier – implementation of one coherent step. Model inherits primary (or set via delegate). Contract is entirely in the brief from the root.\nmode: subagent\ntemperature: 0.2\nsteps: 80\npermission:\n edit: allow\n---\nDo the task described in the user message. The message is a complete brief: context, contract, report format. If the brief lacks information required to start, return a report with a blocker instead of guessing.\n\n<!-- managed config: ~/.config/opencode/agents/worker.md (runbook: ~/.config/opencode/README.md §Workers) | disable: mv worker.md{,.disabled} + restart | created <date> -->\n~/.config/opencode/agents/worker-lite.md---\ndescription: Isolated worker, LITE tier – routine, search, simple edits. Model inherits primary or set via delegate/tier=cheap. Contract is entirely in the brief from the root.\nmode: subagent\ntemperature: 0.2\nsteps: 80\npermission:\n edit: allow\n---\nDo the task described in the user message. The message is a complete brief: context, contract, report format. If the brief lacks information required to start, return a report with a blocker instead of guessing.\n\n<!-- managed config: ~/.config/opencode/agents/worker-lite.md (runbook: ~/.config/opencode/README.md §Workers) | disable: mv worker-lite.md{,.disabled} + restart | created <date> -->\nImportant: there is NO model field in agent files — the model is chosen on call via delegate tools. Hardcoding a model breaks silently when the model is revoked/banned.
~/.config/opencode/lib/advisor-core.tsLives in lib/, not in plugins/: OpenCode treats EVERY exported function of a module in plugin[] as a plugin factory — helpers in a plugin file would crash startup.
/**\n * advisor-core – pure helpers for the delegate plugin.\n *\n * IMPORTANT: this file lives in `~/.config/opencode/lib/`, NOT in `plugins/`.\n * opencode treats EVERY exported function of a module listed in `plugin[]` as a\n * plugin factory (it calls it with PluginInput). Putting helpers in the plugin file\n * crashed startup, so they live in a non-plugin module.\n *\n * PHILOSOPHY\n * The advisor does NOT compute a \"best\" model and applies NO formula/threshold. It\n * fetches the daily benchmark feed and renders a plain table: model, benchmark score\n * (\"parrots\"), price per session, sessions/month. The root LLM reads the table plus\n * the user's request, weighs price vs intelligence itself (and its own knowledge of\n * these models), and proposes one model for human approval. Benchmark units are\n * arbitrary and may change over time, so normalizing them is meaningless.\n */\n\nexport const DEFAULT_ADVISOR = {\n enabled: true,\n reportUrl: \"https://krivich.github.io/opencode-benchmark/report.json\",\n ttlHours: 24,\n maxRows: 40,\n}\n\nexport type Advisor = typeof DEFAULT_ADVISOR\n\n// ── tiers ────────────────────────────────────────────────────────────────────────\n// A tier is only a hint about the price/intelligence appetite. It carries no model.\n// Each tier maps 1:1 to its own delegate tool, so the user can set a different\n// permission / auto-approve per tier:\n// simple – lean cheap; uses an approved model (its own tool)\n// standard – inherit the root model (no model choice; still costs tokens)\n// advanced – allow paying for real intelligence; uses an approved model\nexport const TIERS = [\"simple\", \"standard\", \"advanced\"] as const\nexport type Tier = (typeof TIERS)[number]\n\n/** Map an arbitrary value to a known tier (\"low\" is an alias of \"simple\"); unknown → \"standard\". */\nexport function tierOf(v: unknown): Tier {\n const s = String(v ?? \"\").trim().toLowerCase()\n if (s === \"low\" || s === \"simple\") return \"simple\"\n if (s === \"advanced\") return \"advanced\"\n return \"standard\"\n}\n\n// ── feed row helpers ─────────────────────────────────────────────────────────────\n\n/** Lowercase, strip parentheticals (\"(Off-Peak)\", \"(≤ 256K tokens)\"), slugify. */\nexport function normalizeName(s: unknown): string {\n return String(s ?? \"\")\n .toLowerCase()\n .replace(/\\([^)]*\\)/g, \" \")\n .replace(/[^a-z0-9.]+/g, \"-\")\n .replace(/^-+|-+$/g, \"\")\n .replace(/-{2,}/g, \"-\")\n}\n\nexport function variantOf(name: unknown): \"peak\" | \"off\" | null {\n const s = String(name ?? \"\")\n if (/off[\\s-]?peak/i.test(s)) return \"off\"\n if (/\\bpeak\\b/i.test(s)) return \"peak\"\n return null\n}\n\n/** Peak windows are [fromHour,fromMinute,toHour,toMinute] in `tz` (UTC so far). */\nexport function isPeakNow(peakHours: any, now: Date): boolean {\n if (!peakHours || !Array.isArray(peakHours.ranges) || !peakHours.ranges.length) return false\n const day = now.getUTCDay()\n if (Array.isArray(peakHours.days) && peakHours.days.length === 2) {\n const [from, to] = peakHours.days\n if (typeof from === \"number\" && typeof to === \"number\" && (day < from || day > to)) return false\n }\n const m = now.getUTCHours() * 60 + now.getUTCMinutes()\n return peakHours.ranges.some((r: number[]) => {\n if (!Array.isArray(r) || r.length < 4) return false\n const a = r[0] * 60 + r[1]\n const b = r[2] * 60 + r[3]\n return a <= b ? m >= a && m < b : m >= a || m < b\n })\n}\n\n/** Feed rows for one model id may carry Peak/Off-Peak variants; pick the live one. */\nexport function effectiveRow(rows: any[], now: Date): any {\n if (!rows || !rows.length) return null\n if (rows.length === 1) return rows[0]\n const ph = rows.find((r) => r && r.peakHours)?.peakHours\n const want = isPeakNow(ph, now) ? \"peak\" : \"off\"\n const match = rows.find((r) => variantOf(r.model) === want)\n if (match) return match\n return rows\n .slice()\n .sort((a, b) => (a?.mpPerSession ?? Infinity) - (b?.mpPerSession ?? Infinity))[0]\n}\n\n/**\n * Map a feed row to a live catalog ref.\n * Prefers a real `modelId` (+ `provider`) when the feed provides it; otherwise\n * normalizes the display name and matches against the catalog.\n */\nexport function mapRowToRef(row: any, catalog: string[], providers: string[]): string | null {\n if (row && typeof row.modelId === \"string\" && row.modelId) {\n const direct = typeof row.provider === \"string\" && row.provider ? `${row.provider}/${row.modelId}` : row.modelId\n if (catalog.includes(direct)) return direct\n const hit = catalog.find((r) => r.slice(r.indexOf(\"/\") + 1) === row.modelId)\n if (hit) return hit\n }\n const norm = normalizeName(row?.model)\n if (!norm) return null\n const hits = catalog.filter((r) => normalizeName(r.slice(r.indexOf(\"/\") + 1)) === norm)\n if (hits.length === 1) return hits[0]\n if (hits.length > 1) {\n return hits.find((h) => providers.includes(h.slice(0, h.indexOf(\"/\")))) ?? hits[0]\n }\n return null\n}\n\n// ── plain table (no ranking, no formula) ─────────────────────────────────────────\n\nexport type ModelRow = {\n ref: string\n name: string\n score: number | null\n /** True when the feed scored this model — only measured rows can be weighed on intelligence. */\n measured: boolean\n usdPerSession: number | null\n mpPerSession: number | null\n quotaUsd: number | null\n sessionsPerMonth: number | null\n variant: string | null\n /** True for the root/primary model — the baseline tier=standard inherits. */\n root: boolean\n}\n\nexport type ModelTable = {\n rows: ModelRow[]\n report: { generatedAt?: string; ageHours: number; stale: boolean; measured: number; total: number } | null\n reason?: string\n}\n\n/** Build the raw table for every live catalog model the feed knows about. */\nexport function modelTable(args: {\n report: any\n fetchedAt: number\n stale: boolean\n catalog: string[]\n dead: Set<string>\n providers: string[]\n maxRows?: number\n rootRef?: string | null\n}): ModelTable {\n const { report, fetchedAt, stale, catalog, dead, providers, maxRows, rootRef } = args\n if (!report || !Array.isArray(report.rows)) return { rows: [], report: null, reason: \"no report\" }\n\n const now = new Date()\n const groups = new Map<string, any[]>()\n for (const row of report.rows) {\n const ref = mapRowToRef(row, catalog, providers)\n if (!ref || dead.has(ref)) continue\n const g = groups.get(ref) ?? []\n g.push(row)\n groups.set(ref, g)\n }\n\n const rows: ModelRow[] = []\n for (const [ref, list] of groups) {\n const row = effectiveRow(list, now)\n rows.push({\n ref,\n name: row?.model ?? ref,\n score: typeof row?.score === \"number\" ? row.score : null,\n measured: typeof row?.score === \"number\",\n usdPerSession: typeof row?.priceUsdPerSession === \"number\" ? row.priceUsdPerSession : null,\n mpPerSession: typeof row?.mpPerSession === \"number\" ? row.mpPerSession : null,\n quotaUsd: typeof row?.quotaUsd === \"number\" ? row.quotaUsd : null,\n sessionsPerMonth: typeof row?.requestsPerMonth === \"number\" ? row.requestsPerMonth : null,\n variant: variantOf(row?.model),\n root: !!rootRef && ref === rootRef,\n })\n }\n // Presentation order only (NOT a ranking/score): models the feed measured come\n // first so a score-less ultra-cheap row cannot be grabbed by mistake; within each\n // group, cheapest first.\n rows.sort(\n (a, b) =>\n (a.measured ? 0 : 1) - (b.measured ? 0 : 1) ||\n (a.mpPerSession ?? Infinity) - (b.mpPerSession ?? Infinity) ||\n a.ref.localeCompare(b.ref),\n )\n\n const measured = rows.filter((r) => r.score != null).length\n const shown = Number.isFinite(maxRows) && (maxRows as number) > 0 ? rows.slice(0, maxRows as number) : rows\n const ageHours = fetchedAt ? (Date.now() - fetchedAt) / 3.6e6 : 0\n\n return {\n rows: shown,\n report: { generatedAt: report.generatedAt, ageHours, stale, measured, total: rows.length },\n }\n}\n\nexport function usd(v: number | null): string {\n return v == null ? \"?\" : `$${v.toFixed(5)}`\n}\n\n/** One compact line for a model: score, price, sessions/month. */\nexport function modelSummary(r: ModelRow): string {\n return `${r.ref} — score ${r.score ?? \"—\"}, ${usd(r.usdPerSession)}/session, ${r.sessionsPerMonth ?? \"—\"} sessions/mo`\n}\n\n/**\n * Top MEASURED alternatives (score present), cheapest first, excluding one ref.\n * Used to surface the overview inside the `set_tier_model` permission prompt, so\n * the human can weigh a pin against the same data the advisor table shows.\n */\nexport function alternativesDigest(table: ModelTable, excludeRef?: string, limit = 6): string[] {\n const out: string[] = []\n for (const r of table.rows) {\n if (!r.measured) continue\n if (excludeRef && r.ref === excludeRef) continue\n out.push(modelSummary(r))\n if (out.length >= limit) break\n }\n return out\n}\n\nfunction renderTable(rows: ModelRow[], rootRef?: string | null): string[] {\n const lines: string[] = [\" # model score $/session sessions/mo peak\"]\n rows.forEach((x, i) => {\n const ref = (x.ref.length > 32 ? x.ref.slice(0, 31) + \"…\" : x.ref).padEnd(32)\n const score = (x.score == null ? \"—\" : String(x.score)).padStart(5)\n const price = usd(x.usdPerSession).padStart(10)\n const spm = (x.sessionsPerMonth == null ? \"—\" : String(x.sessionsPerMonth)).padStart(11)\n const mark = x.root ? \" ← your model (standard)\" : \"\"\n lines.push(` ${String(i + 1).padStart(2)} ${ref} ${score} ${price} ${spm} ${x.variant ?? \"\"}${mark}`)\n })\n return lines\n}\n\n/** Human-readable table + an explicit instruction to decide, not to trust a formula. */\nexport function tableText(table: ModelTable, tier: Tier, rootRef?: string | null): string {\n const lines: string[] = [\n `MODEL OPTIONS — tier=${tier}. Raw benchmark/price data to weigh against your baseline — not a recommendation and not a ranking. No child was started; nothing was spent yet.`,\n ]\n\n if (rootRef) {\n const b = table.rows.find((r) => r.ref === rootRef)\n if (b) {\n lines.push(`Baseline (tier=standard = your current model): ${modelSummary(b)}.`)\n } else {\n lines.push(`Baseline (tier=standard = your current model): ${rootRef} (not in the feed table).`)\n }\n }\n\n if (!table.report) {\n lines.push(`Advisor feed unavailable (${table.reason ?? \"offline\"}, no cache).`)\n lines.push(\"Fallback: use list_models for the live catalog and your own knowledge, then set_tier_model.\")\n } else {\n const r = table.report\n const age = r.ageHours < 1 ? `${Math.round(r.ageHours * 60)}min` : `${r.ageHours.toFixed(1)}h`\n lines.push(\n `Feed: ${r.generatedAt ?? \"?\"} (${r.stale ? \"STALE\" : \"fresh\"}, ${age} old) — ${r.measured}/${r.total} catalog models measured.`,\n )\n lines.push(\"\")\n\n const measured = table.rows.filter((x) => x.measured)\n const unmeasured = table.rows.filter((x) => !x.measured)\n\n if (measured.length) {\n lines.push(\"MEASURED (has a benchmark score) — candidates to weigh on intelligence vs price, cheapest first:\")\n lines.push(...renderTable(measured, rootRef))\n } else {\n lines.push(\n \"MEASURED: none — the feed scored no live catalog model, so intelligence cannot be weighed here; decide from your own knowledge.\",\n )\n }\n\n if (unmeasured.length) {\n lines.push(\"\")\n lines.push(\n \"NO BENCHMARK (score —, intelligence UNKNOWN) — reference only; do NOT propose one of these as the tier representative:\",\n )\n lines.push(...renderTable(unmeasured, rootRef))\n }\n\n lines.push(\"\")\n lines.push(\n 'score = benchmark \"final\" in its own arbitrary units (higher = smarter as measured; NOT comparable across time or versions). $/session = cost of one typical session. sessions/mo = how many such sessions fit the monthly pool.',\n )\n }\n\n lines.push(\"\")\n lines.push(\n \"Tier intent — RELATIVE to the baseline above: simple → cheaper/weaker than your model is fine; advanced → smarter/pricier is worth it; standard → inherit your model (no model choice; still costs tokens).\",\n )\n lines.push(\"\")\n lines.push(\"Root — decide, do not look for a formula:\")\n lines.push(\" 1. Read the user's request and the conversation; judge whether cheap-but-decent or expensive-and-smart fits.\")\n lines.push(\" 2. Compare candidates to the baseline and weigh the table AND your own knowledge of these models. Treat the score as a rough, aging hint, not truth.\")\n lines.push(\" 3. Prefer a MEASURED row. A score-less model cannot be weighed on intelligence — pick one only with an explicit non-benchmark reason, and state it.\")\n lines.push(\" 4. Show this table to the user and propose ONE concrete model; get agreement (the user may name any other model).\")\n lines.push(\n ` 5. Call set_tier_model({ tier: \"${tier}\", model, note }) — the native permission prompt lists the top measured alternatives. On approval the model is pinned for this session (24h).`,\n )\n lines.push(\" 6. Re-run delegate with the same brief and tier; it will then execute.\")\n return lines.join(\"\\n\")\n}\n~/.config/opencode/plugins/context-sentinel.ts/**\n * context-sentinel – plugin for OpenCode\n *\n * WHAT IT DOES\n * 1. Tracks current context size (prompt tokens of the last assistant message)\n * and warns via TUI toast when approaching the model's context limit,\n * so a manual checkpoint + /compact can be done BEFORE auto-compaction.\n * 2. Replaces the default compaction prompt with a structured checkpoint-style\n * prompt, AND writes a MECHANICAL checkpoint file (verbatim last user posts +\n * todo + touched files) that does NOT depend on the compaction model producing\n * anything useful. The path is injected into the compaction context so the next\n * turn knows to read it.\n * 3. Validates the model's compaction digest (rejects empty / tool-call output) and\n * falls back to the mechanical checkpoint; logs every step (no more silent fails).\n * 4. Signs files created by the agent whose name matches SENTINEL_SIGN patterns\n * (default: CHECKPOINT*,*.checkpoint.md).\n *\n * RECOVERY / RUNBOOK\n * Full runbook lives in ~/.config/opencode/README.md.\n * Quick kill-switch (restores stock opencode behavior):\n * mv ~/.config/opencode/plugins/context-sentinel.ts{,.disabled} && restart opencode\n */\n\n/*\n * CONFIG SOURCES (no hardcoded models!)\n * - Context limits are resolved at runtime, in order:\n * 1. live /config/providers endpoint (client.config.providers())\n * 2. client.config.get()\n * 3. JSONC parse of ~/.config/opencode/opencode.json(c) and <project>/opencode.json(c)\n * 4. conservative fallback DEFAULT_LIMIT (warns early, never late)\n * - Thresholds: SENTINEL_WARN (default 0.7), SENTINEL_CRIT (default 0.85)\n * - Signed file patterns: SENTINEL_SIGN (default \"CHECKPOINT*,*.checkpoint.md\")\n * - Checkpoint: SENTINEL_CHECKPOINT_DIR (default \".opencode\"),\n * SENTINEL_KEEP_USER (default 12 verbatim user posts),\n * SENTINEL_MIN_DIGEST (default 200 chars to accept a model digest)\n */\n\nimport type { Plugin } from \"@opencode-ai/plugin\"\nimport { basename, isAbsolute, join } from \"node:path\"\nimport { homedir } from \"node:os\"\nimport { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\"\nimport { readFile, stat } from \"node:fs/promises\"\n\nconst VERSION = \"1.5.0\"\nconst DEFAULT_LIMIT = 128_000\nconst SIGN_MARK = \"autograph: created by context-sentinel\"\n\nconst envFrac = (name: string, fallback: number) => {\n const n = Number(process.env[name])\n return Number.isFinite(n) && n > 0 && n < 1 ? n : fallback\n}\nconst envInt = (name: string, fallback: number) => {\n const n = Number(process.env[name])\n return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback\n}\n\nconst WARN_LEVEL = envFrac(\"SENTINEL_WARN\", 0.7)\nconst CRIT_LEVEL = envFrac(\"SENTINEL_CRIT\", 0.85)\nconst KEEP_USER = envInt(\"SENTINEL_KEEP_USER\", 12)\nconst MIN_DIGEST = envInt(\"SENTINEL_MIN_DIGEST\", 200)\nconst CHECKPOINT_DIR = process.env.SENTINEL_CHECKPOINT_DIR ?? \".opencode\"\n\nconst SIGN_PATTERNS = (process.env.SENTINEL_SIGN ?? \"CHECKPOINT*,*.checkpoint.md\")\n .split(\",\")\n .map((s) => s.trim())\n .filter(Boolean)\n\nconst wildcardRegex = (pattern: string) =>\n new RegExp(\n \"^\" + pattern.split(\"*\").map((s) => s.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\")).join(\".*\") + \"$\",\n \"i\",\n )\n\nconst SIGN_RES = SIGN_PATTERNS.map(wildcardRegex)\n\nconst signatureHeader = () =>\n `<!-- ${SIGN_MARK} v${VERSION} | plugin: ~/.config/opencode/plugins/context-sentinel.ts | file is safe to delete anytime; to disable the mechanism: mv context-sentinel.ts{,.disabled} + restart opencode -->\\n\\n`\n\nconst COMPACTION_PROMPT = `You are generating a compaction summary that will REPLACE the conversation history.\nThe continuation of work depends entirely on the quality of this summary. Be precise and dense.\n\nProduce a structured checkpoint in this exact format:\n\n## TASK\nWhat the user asked for, verbatim intent (1-3 sentences).\n\n## USER INSTRUCTIONS (verbatim)\nThe user's own instructions, requirements, constraints and preferences from this session,\nAS CLOSE TO THE ORIGINAL WORDING AS POSSIBLE. Do not paraphrase. This is the highest-priority\ncontent, because it cannot be reconstructed later. Include EVERY standing order the user gave.\n\n## STATUS\nWhat is DONE. What is IN PROGRESS right now. What is NOT started.\n\n## KEY FACTS & DECISIONS\n- Critical facts discovered (file paths, line numbers, API contracts, config values, error messages)\n- Decisions made and WHY (rejected alternatives matter – do not re-explore them)\n\n## ALREADY ESTABLISHED (DO NOT RE-EXPLORE)\n- Concrete facts already learned (paths, symbols, architecture, findings). The next session must\n trust this list and MUST NOT re-investigate these areas unless something contradicts it.\n\n## FILES TOUCHED\n- path – what was done/learned there (with line refs where relevant)\n\n## NEXT STEPS\n- Numbered, concrete, executable steps. The next step must be startable without any clarification.\n\n## CHECKPOINTS & DOCS\n- If CHECKPOINT*.md, JOURNAL.md, STAGE.md or similar project files exist and are relevant, list them –\n the next session MUST read them before acting.\n\nRules:\n- Output ONLY the checkpoint text (Markdown). Do NOT call tools, do NOT ask questions, do NOT read files,\n do NOT run commands. Tools are UNAVAILABLE in this mode.\n- Never emit tool-call syntax of any kind; your ENTIRE reply must be the checkpoint text.\n- Include exact identifiers, paths, commands – never vague references like \"the file we discussed\".\n- Omit small talk and tool-call noise. Keep only what changes future behavior.\n- Write in the language of the original conversation.`\n\ntype WarnLevel = \"none\" | \"warn\" | \"crit\"\n\nconst TOOL_CALL_RE =\n /<tool[_\\s-]?calls?>|<\\|tool|<\\/?invoke\\b|\"tool\"\\s*:|\\bRunning tool\\b|^\\s*\\{\\s*\"name\"\\s*:/im\n\n/** A digest is usable only if it is real prose, not an empty string or a tool call. */\nconst looksLikeToolCall = (s: string) => TOOL_CALL_RE.test(s)\nconst validateDigest = (s: string) => {\n const t = (s ?? \"\").trim()\n return t.length >= MIN_DIGEST && !looksLikeToolCall(t)\n}\n\n/** Strip // and block comments plus trailing commas from JSONC, string-safe. */\nfunction stripJsonc(src: string): string {\n let out = \"\"\n let inStr = false\n let esc = false\n for (let i = 0; i < src.length; i++) {\n const c = src[i]!\n const next = src[i + 1]\n if (inStr) {\n out += c\n if (esc) esc = false\n else if (c === \"\\\\\") esc = true\n else if (c === '\"') inStr = false\n continue\n }\n if (c === '\"') {\n inStr = true\n out += c\n continue\n }\n if (c === \"/\" && next === \"/\") {\n while (i < src.length && src[i] !== \"\\n\") i++\n out += \"\\n\"\n continue\n }\n if (c === \"/\" && next === \"*\") {\n i += 2\n while (i < src.length && !(src[i] === \"*\" && src[i + 1] === \"/\")) i++\n i++\n continue\n }\n out += c\n }\n return out.replace(/,(\\s*[}\\]])/g, \"$1\")\n}\n\nfunction addLimit(out: Map<string, number>, id: unknown, ctx: unknown) {\n if (\n typeof id === \"string\" &&\n id &&\n typeof ctx === \"number\" &&\n Number.isFinite(ctx) &&\n ctx > 0 &&\n !out.has(id)\n ) {\n out.set(id, ctx)\n }\n}\n\n/**\n * Accepts two shapes:\n * - config files / client.config.get(): { provider: { <pid>: { models: { <id>: { limit: { context } } } } } }\n * - client.config.providers(): { providers: [ { models: { <id>: { limit: { context } } } } ] }\n */\nfunction collectLimits(cfg: unknown, out: Map<string, number>) {\n const providers = (cfg as any)?.provider\n if (providers && typeof providers === \"object\" && !Array.isArray(providers)) {\n for (const p of Object.values<any>(providers)) {\n const models = p?.models\n if (!models || typeof models !== \"object\") continue\n for (const [id, m] of Object.entries<any>(models)) addLimit(out, id, m?.limit?.context)\n }\n }\n const list = (cfg as any)?.providers\n if (Array.isArray(list)) {\n for (const p of list) {\n const models = p?.models\n if (!models || typeof models !== \"object\") continue\n for (const [id, m] of Object.entries<any>(models)) addLimit(out, id, m?.limit?.context)\n }\n }\n}\n\nexport const ContextSentinel: Plugin = async ({ client, directory }) => {\n // session ids that belong to subagents (have a parent) – their context and\n // compaction must not drive root warnings or pollute the checkpoint files.\n const childSessions = new Set<string>()\n // sessionID -> checkpoint file written by the compacting hook (for the event/autocontinue).\n const checkpoints = new Map<string, string>()\n let lastLevel: WarnLevel = \"none\"\n let lastKnownContext = 0\n let limitsPromise: Promise<Map<string, number>> | undefined\n\n const projectDir = directory && isAbsolute(directory) ? directory : process.cwd()\n\n const log = async (level: \"info\" | \"warn\" | \"error\", message: string) => {\n try {\n await client.app.log({ body: { service: \"context-sentinel\", level, message } })\n } catch {\n console.error(`[context-sentinel] ${message}`)\n }\n }\n\n await log(\n \"info\",\n `context-sentinel v${VERSION} loaded (warn=${WARN_LEVEL}, crit=${CRIT_LEVEL}, sign=${SIGN_PATTERNS.join(\",\")}, checkpointDir=${CHECKPOINT_DIR}, keepUser=${KEEP_USER})`,\n )\n\n const configCandidates = (): string[] => {\n const home = join(homedir(), \".config\", \"opencode\")\n const candidates = [join(home, \"opencode.json\"), join(home, \"opencode.jsonc\")]\n if (directory && isAbsolute(directory)) {\n candidates.push(join(directory, \"opencode.json\"), join(directory, \"opencode.jsonc\"))\n }\n return candidates\n }\n\n const loadLimits = async (): Promise<Map<string, number>> => {\n const limits = new Map<string, number>()\n\n try {\n const res = await (client as any).config?.providers?.()\n const data = res?.data ?? res\n if (data && typeof data === \"object\") collectLimits(data, limits)\n } catch {\n // endpoint unavailable – fall through\n }\n\n if (limits.size === 0) {\n try {\n const cfg = await (client as any).config?.get?.()\n if (cfg && typeof cfg === \"object\") collectLimits(cfg, limits)\n } catch {\n // SDK not available – fall through to file reading\n }\n }\n\n for (const path of configCandidates()) {\n if (limits.size > 0) break\n try {\n await stat(path)\n const raw = await readFile(path, \"utf8\")\n const parsed = JSON.parse(stripJsonc(raw))\n collectLimits(parsed, limits)\n } catch {\n // missing or unparseable config – try next candidate\n }\n }\n return limits\n }\n\n const getLimits = () => (limitsPromise ??= loadLimits())\n\n const notify = async (\n message: string,\n variant: \"info\" | \"success\" | \"warning\" | \"error\" = \"warning\",\n ) => {\n const tui: any = (client as any).tui\n try {\n if (typeof tui?.showToast === \"function\") {\n await tui.showToast({ body: { message, variant } })\n return\n }\n if (typeof tui?.toast?.show === \"function\") {\n await tui.toast.show({ body: { message, variant } })\n return\n }\n } catch {\n // fall through to log\n }\n await log(\"warn\", message)\n }\n\n const extractContextTokens = (info: any): number => {\n try {\n const t = info?.tokens\n if (!t) return 0\n const input = typeof t.input === \"number\" ? t.input : 0\n const read = typeof t.cache?.read === \"number\" ? t.cache.read : 0\n const write = typeof t.cache?.write === \"number\" ? t.cache.write : 0\n return input + read + write\n } catch {\n return 0\n }\n }\n\n const fetchMessages = async (sessionID: string): Promise<any[]> => {\n try {\n const res = await (client as any).session?.messages?.({ path: { id: sessionID } })\n const data = res?.data ?? res\n return Array.isArray(data) ? data : (data?.messages ?? [])\n } catch (e) {\n await log(\"warn\", `messages fetch failed: ${e}`)\n return []\n }\n }\n\n const fetchTodos = async (sessionID: string): Promise<any[]> => {\n try {\n const res = await (client as any).session?.todo?.({ path: { id: sessionID } })\n const data = res?.data ?? res\n return Array.isArray(data) ? data : (data?.todos ?? [])\n } catch {\n return []\n }\n }\n\n const isCompactionCarrier = (t: string) => /^\\[compaction\\]/i.test(t.trim()) && t.trim().length < 60\n\n /** Mechanical, model-independent checkpoint: verbatim user posts + todo + touched files. */\n const buildMechanicalCheckpoint = async (\n sessionID: string,\n ): Promise<{ markdown: string; userCount: number; files: string[]; todos: number } | null> => {\n const list = await fetchMessages(sessionID)\n if (!list.length) return null\n\n const users: string[] = []\n const files = new Set<string>()\n for (const item of list) {\n const info = item?.info ?? item\n const parts: any[] = item?.parts ?? []\n if (info?.role === \"user\") {\n const text = parts\n .filter((p) => p?.type === \"text\")\n .map((p) => p?.text ?? \"\")\n .join(\"\\n\")\n .trim()\n if (text && !isCompactionCarrier(text)) users.push(text)\n }\n for (const p of parts) {\n if (p?.type !== \"tool\") continue\n const inp = p?.state?.input ?? p?.input\n const fp = inp?.filePath ?? inp?.path\n if (typeof fp === \"string\" && fp) files.add(fp)\n }\n }\n\n const lastUsers = users.slice(-KEEP_USER)\n const todos = await fetchTodos(sessionID)\n const stamp = new Date().toISOString()\n\n const md = [\n `# Mechanical checkpoint (${stamp})`,\n ``,\n `- session: ${sessionID}`,\n `- project: ${projectDir}`,\n `- user posts captured: ${lastUsers.length} (verbatim, newest last)`,\n ``,\n `## USER INSTRUCTIONS (verbatim — authoritative, do not paraphrase)`,\n ...lastUsers.map((t, i) => `\\n### User post ${i + 1}\\n\\n${t}`),\n ``,\n `## TODO`,\n todos.length\n ? todos\n .map((t: any) => `- [${t?.status ?? \"?\"}] ${t?.content ?? t?.title ?? JSON.stringify(t)}`)\n .join(\"\\n\")\n : \"(no todo list)\",\n ``,\n `## FILES TOUCHED (from tool calls)`,\n files.size ? [...files].map((f) => `- ${f}`).join(\"\\n\") : \"(none detected)\",\n ``,\n ].join(\"\\n\")\n\n return { markdown: md, userCount: lastUsers.length, files: [...files], todos: todos.length }\n }\n\n const writeCheckpoint = (markdown: string): string | null => {\n try {\n const dir = join(projectDir, CHECKPOINT_DIR)\n mkdirSync(dir, { recursive: true })\n const stamp = new Date().toISOString().slice(0, 19).replace(/[:T]/g, \"-\")\n const file = join(dir, `CHECKPOINT-${stamp}.md`)\n writeFileSync(file, signatureHeader() + markdown)\n return file\n } catch (e) {\n void log(\"warn\", `cannot write checkpoint file: ${e}`)\n return null\n }\n }\n\n /** Read the model's digest from the session and accept it only if it is real prose. */\n const readModelDigest = async (sessionID: string): Promise<string | null> => {\n const list = await fetchMessages(sessionID)\n for (let i = list.length - 1; i >= 0; i--) {\n const item = list[i]\n const info = item?.info ?? item\n const isSummary = info?.summary === true || info?.mode === \"compaction\"\n if (!isSummary) continue\n const text = (item.parts || [])\n .filter((p: any) => p?.type === \"text\")\n .map((p: any) => p?.text || \"\")\n .join(\"\\n\")\n .trim()\n if (validateDigest(text)) return text\n await log(\n \"warn\",\n `rejected compaction digest: ${text.length} chars${looksLikeToolCall(text) ? \", looks like a tool call\" : text.length < MIN_DIGEST ? `, < ${MIN_DIGEST} chars minimum` : \"\"}`,\n )\n }\n return null\n }\n\n // Append the validated model digest to the mechanical checkpoint, if both exist.\n const appendDigest = (file: string, digest: string) => {\n try {\n appendFileSync(file, `\\n## MODEL DIGEST (validated, ${digest.length} chars)\\n\\n${digest}\\n`)\n void log(\"info\", `digest appended to ${file}`)\n } catch (e) {\n void log(\"warn\", `cannot append digest: ${e}`)\n }\n }\n\n // Best-effort legacy persistence into STATE.md when the project uses one.\n const persistToState = (text: string) => {\n const statePath = join(projectDir, \"STATE.md\")\n if (!existsSync(statePath)) return\n try {\n const stamp = new Date().toISOString().slice(0, 16).replace(\"T\", \" \")\n const block = `\\n## Checkpoint (auto-compaction, ${stamp})\\n\\n${text.trim()}\\n`\n const content = readFileSync(statePath, \"utf8\")\n const marker = \"<!-- ARCHIVE:BELOW -->\"\n const idx = content.indexOf(marker)\n // Land the digest BELOW the marker: STATE.md head must stay the agent's\n // current checkpoint, not a growing chronicle; `npm run state:diet`\n // archives what is below the marker on the next run.\n const updated =\n idx >= 0\n ? content.slice(0, idx + marker.length) +\n \"\\n\" +\n block +\n \"\\n\" +\n content.slice(idx + marker.length)\n : content + block\n writeFileSync(statePath, updated)\n void log(\"info\", `checkpoint also appended to STATE.md (${text.trim().length} chars)`)\n } catch (e) {\n void log(\"warn\", `cannot write STATE.md: ${e}`)\n }\n }\n\n return {\n \"tool.execute.before\": async (input, output) => {\n try {\n const tool = String(input.tool ?? \"\").toLowerCase()\n if (tool !== \"write\" && tool !== \"writefile\") return\n const filePath = String(output.args?.filePath ?? \"\")\n const content = output.args?.content\n if (!filePath || typeof content !== \"string\") return\n const name = basename(filePath)\n if (!SIGN_RES.some((re) => re.test(name))) return\n if (content.includes(SIGN_MARK)) return\n output.args.content = signatureHeader() + content\n await log(\"info\", `signed ${filePath}`)\n } catch (e) {\n await log(\"error\", `signing failed: ${e}`)\n }\n },\n\n event: async ({ event }) => {\n try {\n if (event.type === \"session.created\" || event.type === \"session.updated\") {\n const info: any = (event as any).properties?.info\n if (info?.id) {\n if (info.parentID) childSessions.add(info.id)\n else childSessions.delete(info.id)\n }\n return\n }\n if (event.type === \"session.deleted\") {\n const info: any = (event as any).properties?.info\n if (info?.id) {\n childSessions.delete(info.id)\n checkpoints.delete(info.id)\n }\n return\n }\n\n if (event.type === \"message.updated\") {\n const info: any = (event as any).properties?.info\n if (!info || info.role !== \"assistant\") return\n if (info.sessionID && childSessions.has(info.sessionID)) return\n\n const tokens = extractContextTokens(info)\n if (tokens > 0) lastKnownContext = tokens\n\n const modelId: string = info.modelID ?? \"\"\n const limits = await getLimits()\n const limit = limits.get(modelId) ?? DEFAULT_LIMIT\n\n const ratio = lastKnownContext / limit\n if (ratio >= CRIT_LEVEL && lastLevel !== \"crit\") {\n lastLevel = \"crit\"\n await notify(\n `CONTEXT ${Math.round(ratio * 100)}% (${lastKnownContext}/${limit}). AUTO-COMPACT IMMINENT – write a checkpoint file NOW, then ask user to run /compact`,\n \"error\",\n )\n } else if (ratio >= WARN_LEVEL && lastLevel === \"none\") {\n lastLevel = \"warn\"\n await notify(\n `Context at ${Math.round(ratio * 100)}% (${lastKnownContext}/${limit}). Good moment for a checkpoint – then /compact while quality is still high`,\n )\n }\n return\n }\n\n if (event.type === \"session.compacted\") {\n const sessionID: string | undefined = (event as any).properties?.sessionID\n if (sessionID && childSessions.has(sessionID)) return\n\n lastLevel = \"none\"\n lastKnownContext = 0\n limitsPromise = undefined\n if (!sessionID) return\n\n const digest = await readModelDigest(sessionID)\n const file = checkpoints.get(sessionID)\n\n if (file) {\n if (digest) appendDigest(file, digest)\n else await log(\"warn\", `no usable model digest; mechanical checkpoint is authoritative: ${file}`)\n if (digest) persistToState(digest)\n } else {\n // compacting hook did not write a file (e.g. empty session) – fall back now.\n const built = await buildMechanicalCheckpoint(sessionID)\n const path = built ? writeCheckpoint(built.markdown) : null\n if (path) {\n checkpoints.set(sessionID, path)\n if (digest) appendDigest(path, digest)\n if (digest) persistToState(digest)\n await log(\"warn\", `compacting hook wrote no file; fallback checkpoint: ${path}`)\n } else {\n await log(\"error\", \"compaction finished with NO checkpoint (mechanical fallback failed)\")\n }\n }\n\n const shown = checkpoints.get(sessionID)\n await notify(\n shown\n ? `Compaction done. Checkpoint: ${shown} — READ IT before acting.`\n : \"Compaction done, but no checkpoint file was written (check logs).\",\n shown ? \"info\" : \"warning\",\n )\n }\n } catch (e) {\n await log(\"error\", `event handler failed: ${e}`)\n }\n },\n\n \"experimental.session.compacting\": async (input, output) => {\n try {\n const sessionID = input?.sessionID\n if (!sessionID || childSessions.has(sessionID)) return\n\n const built = await buildMechanicalCheckpoint(sessionID)\n let prompt = COMPACTION_PROMPT\n let file: string | null = null\n\n if (built) {\n file = writeCheckpoint(built.markdown)\n if (file) {\n checkpoints.set(sessionID, file)\n output.context = output.context ?? []\n output.context.push(\n `A machine-generated VERBATIM checkpoint was saved at: ${file}`,\n `It holds the user's last ${built.userCount} messages word-for-word, the todo list and touched files. READ IT before acting after compaction.`,\n )\n }\n // Ground truth in the prompt itself, so the digest cannot drop the user's own words.\n prompt = `${COMPACTION_PROMPT}\\n\\n---\\nGROUND TRUTH already collected mechanically (verbatim). Preserve the USER INSTRUCTIONS word-for-word:\\n\\n${built.markdown}`\n }\n\n output.prompt = prompt\n await log(\n \"info\",\n `compaction hook applied: prompt=${prompt.length} chars, users=${built?.userCount ?? 0}, todos=${built?.todos ?? 0}, files=${built?.files.length ?? 0}, checkpoint=${file ?? \"none\"}`,\n )\n } catch (e) {\n await log(\"error\", `compacting hook failed: ${e}`)\n }\n },\n\n \"experimental.compaction.autocontinue\": async (input, output) => {\n try {\n const file = checkpoints.get(input?.sessionID)\n if (file && existsSync(file)) {\n output.enabled = true\n await log(\"info\", `autocontinue: checkpoint present (${file})`)\n } else {\n output.enabled = false\n await log(\"warn\", `autocontinue disabled: no checkpoint written for ${input?.sessionID}`)\n }\n } catch (e) {\n await log(\"error\", `autocontinue hook failed: ${e}`)\n }\n },\n }\n}\n~/.config/opencode/plugins/delegate.ts/**\n * delegate – plugin for OpenCode\n *\n * WHY\n * The built-in `task` tool cannot choose a model: a subagent always runs with the\n * model baked into its agent file. That hardcodes the delegate model, and it breaks\n * the day that model disappears or is not authorized.\n *\n * WHAT\n * Primary-only tools:\n * delegate_simple_task – run a child on a cheap model (tier \"simple\").\n * delegate_standard_task – run a child that INHERITS the root model (tier \"standard\").\n * delegate_advanced_task – run a child on a strong/expensive model (tier \"advanced\").\n * list_models – list the live catalog with cost/context.\n * recommend_model – render the daily benchmark feed as a plain table (no\n * ranking, no formula) so the root can weigh price vs\n * intelligence itself.\n * set_tier_model – pin an approved model to a tier for this session (24h).\n *\n * WHY ONE TOOL PER TIER\n * opencode's permission (incl. \"always allow\") is keyed by TOOL NAME, not by argument.\n * Separate tools let the user set a different policy per tier — e.g. auto-approve\n * simple, but approve standard/advanced by hand — and the tool name itself tells the\n * model when to use it.\n *\n * TIERS (no models baked in)\n * simple – lean cheap; first use this session returns MODEL SELECTION REQUIRED\n * (a benchmark table) until the user approves a model via set_tier_model.\n * standard – the child runs WITHOUT a model override, inheriting the root model.\n * advanced – pay for real intelligence; same approval flow as simple.\n *\n * The benchmark table also shows the baseline = the current root model, so simple/\n * advanced can be judged RELATIVE to it. A failing model is blacklisted for the\n * session and the next candidate (including inheriting the root model) is tried.\n *\n * Money safety: no model is applied without approval; the only pin comes from\n * set_tier_model, gated by a native permission prompt. Every delegation still costs\n * tokens (a child has a fresh context → prompt-cache miss), so all tiers ask by\n * default (the user may set any of them to \"allow\").\n *\n * Config: ~/.config/opencode/routing.json (providers + advisor; optional).\n * Kill-switch: rename delegate.ts + remove it from opencode.jsonc plugin[] + restart.\n */\n\nimport * as fs from \"node:fs\"\nimport * as path from \"node:path\"\nimport { homedir } from \"node:os\"\nimport { Effect } from \"effect\"\nimport { tool, type Plugin } from \"@opencode-ai/plugin\"\nimport {\n DEFAULT_ADVISOR,\n tierOf,\n modelTable,\n tableText,\n alternativesDigest,\n modelSummary,\n type Tier,\n} from \"../lib/advisor-core.ts\"\n\nconst CONFIG_DIR = path.join(homedir(), \".config\", \"opencode\")\nconst ROUTING_FILE = path.join(CONFIG_DIR, \"routing.json\")\nconst ADVISOR_DIR = path.join(homedir(), \".cache\", \"opencode\", \"model-advisor\")\nconst REPORT_CACHE = path.join(ADVISOR_DIR, \"report.json\")\nconst PIN_FILE = path.join(ADVISOR_DIR, \"pin.json\")\nconst DELEGATE_DIR = path.join(homedir(), \".cache\", \"opencode\", \"delegate\")\nconst SPEND_FILE = path.join(DELEGATE_DIR, \"spend.json\")\n\nconst DEFAULT_ROUTING = { providers: [\"opencode-go\"] }\n\ntype Routing = { providers: string[]; advisor: typeof DEFAULT_ADVISOR }\n\nfunction loadRouting(): Routing {\n try {\n const parsed = JSON.parse(fs.readFileSync(ROUTING_FILE, \"utf8\"))\n const adv = parsed.advisor ?? {}\n return {\n providers:\n Array.isArray(parsed.providers) && parsed.providers.length ? parsed.providers : [...DEFAULT_ROUTING.providers],\n advisor: { ...DEFAULT_ADVISOR, ...adv },\n }\n } catch {\n return { providers: [...DEFAULT_ROUTING.providers], advisor: { ...DEFAULT_ADVISOR } }\n }\n}\n\nfunction splitRef(ref: string): { providerID: string; modelID: string } | null {\n const i = ref.indexOf(\"/\")\n if (i <= 0 || i === ref.length - 1) return null\n return { providerID: ref.slice(0, i), modelID: ref.slice(i + 1) }\n}\n\n// ── plugin ──────────────────────────────────────────────────────────────────────\n\nexport const Delegate: Plugin = async ({ client }) => {\n const routing = loadRouting()\n const dead = new Set<string>()\n\n const log = async (level: \"info\" | \"warn\" | \"error\", message: string) => {\n try {\n await (client as any).app.log({ body: { service: \"delegate\", level, message } })\n } catch {\n // never throw\n }\n }\n\n type Entry = { providerID: string; modelID: string; cost?: any; context?: number }\n\n const catalog = async (): Promise<Map<string, Entry>> => {\n const out = new Map<string, Entry>()\n try {\n const res = await (client as any).config?.providers?.()\n const data = res?.data ?? res\n for (const p of data?.providers ?? []) {\n for (const [id, m] of Object.entries<any>(p.models ?? {})) {\n out.set(`${p.id}/${id}`, {\n providerID: p.id,\n modelID: id,\n cost: m?.cost,\n context: m?.limit?.context,\n })\n }\n }\n } catch (e) {\n await log(\"warn\", `catalog fetch failed: ${e}`)\n }\n return out\n }\n\n // ── advisor: report cache + per-(session,tier) pins ─────────────────────────\n\n const getReport = async (force = false): Promise<{ report: any; fetchedAt: number; stale: boolean } | null> => {\n const adv = routing.advisor\n if (adv.enabled === false) return null\n if (!force) {\n try {\n const raw = JSON.parse(fs.readFileSync(REPORT_CACHE, \"utf8\"))\n if (raw?.report?.rows && Date.now() - (raw.fetchedAt ?? 0) < adv.ttlHours * 3.6e6) {\n return { report: raw.report, fetchedAt: raw.fetchedAt, stale: false }\n }\n } catch {\n // no fresh cache\n }\n }\n try {\n const ctrl = new AbortController()\n const timer = setTimeout(() => ctrl.abort(), 8000)\n let res: any\n try {\n res = await fetch(adv.reportUrl, { signal: ctrl.signal })\n } finally {\n clearTimeout(timer)\n }\n if (!res?.ok) throw new Error(`HTTP ${res?.status}`)\n const report = await res.json()\n if (!report?.rows) throw new Error(\"report has no rows\")\n fs.mkdirSync(ADVISOR_DIR, { recursive: true })\n fs.writeFileSync(REPORT_CACHE, JSON.stringify({ fetchedAt: Date.now(), report }))\n return { report, fetchedAt: Date.now(), stale: false }\n } catch (e) {\n await log(\"warn\", `advisor report fetch failed: ${e}`)\n try {\n const raw = JSON.parse(fs.readFileSync(REPORT_CACHE, \"utf8\"))\n if (raw?.report?.rows) return { report: raw.report, fetchedAt: raw.fetchedAt ?? 0, stale: true }\n } catch {\n // no cache at all\n }\n return null\n }\n }\n\n // The root/primary model of THIS session — the baseline that simple/advanced are\n // measured against, and the model tier \"standard\" inherits. Read from the latest\n // message, falling back to the configured default model.\n const rootModel = async (sessionID: string): Promise<string | null> => {\n try {\n const res = await (client as any).session.messages({ path: { id: sessionID } })\n const data = res?.data ?? res\n const msgs: any[] = Array.isArray(data) ? data : (data?.messages ?? [])\n for (let i = msgs.length - 1; i >= 0; i--) {\n const info = msgs[i]?.info ?? msgs[i]\n if (!info) continue\n if (info.role === \"assistant\" && info.providerID && info.modelID) return `${info.providerID}/${info.modelID}`\n if (info.role === \"user\" && info.model?.providerID && info.model?.modelID) {\n return `${info.model.providerID}/${info.model.modelID}`\n }\n }\n } catch (e) {\n await log(\"warn\", `root model lookup failed: ${e}`)\n }\n try {\n const res = await (client as any).config?.get?.()\n const data = res?.data ?? res\n if (typeof data?.model === \"string\" && data.model) return data.model\n } catch {\n // ignore\n }\n return null\n }\n\n // Build the raw advisor table once; `advise` renders it, `set_tier_model`\n // takes a compact digest from it for the permission prompt.\n const buildTable = async (sessionID: string, force = false) => {\n const [dr, models, rootRef] = await Promise.all([getReport(force), catalog(), rootModel(sessionID)])\n const table = modelTable({\n report: dr?.report ?? null,\n fetchedAt: dr?.fetchedAt ?? 0,\n stale: dr?.stale ?? false,\n catalog: [...models.keys()],\n dead,\n providers: routing.providers,\n maxRows: routing.advisor.maxRows,\n rootRef,\n })\n return { table, rootRef }\n }\n\n const advise = async (tier: Tier, sessionID: string, force = false): Promise<string> => {\n const { table, rootRef } = await buildTable(sessionID, force)\n return tableText(table, tier, rootRef)\n }\n\n type TierPin = { model: string; note?: string; at: number }\n type PinFile = Record<string, Partial<Record<Tier, TierPin>>>\n\n const readPins = (): PinFile => {\n try {\n return JSON.parse(fs.readFileSync(PIN_FILE, \"utf8\")) ?? {}\n } catch {\n return {}\n }\n }\n\n const readTierPin = (sessionID: string, tier: Tier): TierPin | null => {\n const p = readPins()[sessionID]?.[tier]\n if (!p?.model) return null\n if (Date.now() - (p.at ?? 0) > routing.advisor.ttlHours * 3.6e6) return null\n return p\n }\n\n const writeTierPin = (sessionID: string, tier: Tier, model: string, note?: string) => {\n const pins = readPins()\n const cutoff = Date.now() - routing.advisor.ttlHours * 3.6e6\n const fresh: PinFile = {}\n for (const [sid, byTier] of Object.entries(pins)) {\n const keep: Partial<Record<Tier, TierPin>> = {}\n for (const [t, p] of Object.entries(byTier ?? {})) {\n if (p?.model && Date.now() - (p.at ?? 0) <= cutoff) keep[t as Tier] = p\n }\n if (Object.keys(keep).length) fresh[sid] = keep\n }\n fresh[sessionID] = { ...(fresh[sessionID] ?? {}), [tier]: { model, note, at: Date.now() } }\n fs.mkdirSync(ADVISOR_DIR, { recursive: true })\n fs.writeFileSync(PIN_FILE, JSON.stringify(fresh, null, 2))\n }\n\n const extractReport = (data: any): string =>\n (data?.parts ?? [])\n .filter((p: any) => p?.type === \"text\")\n .map((p: any) => p?.text ?? \"\")\n .join(\"\\n\")\n .trim()\n\n // ── cost accounting ─────────────────────────────────────────────────────────\n // opencode keeps two separate counters: `session.cost` is incremented by the\n // server ONLY for the session in which a step-finish happens (core/session/\n // projector.ts), so a child's spend never rolls into the parent's total that\n // the TUI shows. We therefore surface both numbers to the orchestrator\n // explicitly, so it can budget and prefer cheaper delegation.\n\n const money = (n: number): string => {\n const v = Number.isFinite(n) ? n : 0\n return `$${v.toFixed(v > 0 && v < 0.01 ? 5 : 4)}`\n }\n\n const num = (n: number): string => (Number.isFinite(n) ? n : 0).toLocaleString(\"en-US\")\n\n type Spend = { cost: number; input: number; output: number }\n\n const readSpend = (): Record<string, number> => {\n try {\n return JSON.parse(fs.readFileSync(SPEND_FILE, \"utf8\")) ?? {}\n } catch {\n return {}\n }\n }\n\n // Cumulative delegated spend, keyed by the orchestrator (parent) session.\n const addSpend = (sessionID: string, amount: number): number => {\n const all = readSpend()\n const total = (all[sessionID] ?? 0) + (Number.isFinite(amount) ? amount : 0)\n all[sessionID] = total\n try {\n fs.mkdirSync(DELEGATE_DIR, { recursive: true })\n fs.writeFileSync(SPEND_FILE, JSON.stringify(all, null, 2))\n } catch {\n // best-effort; never break a delegation over accounting\n }\n return total\n }\n\n // Cost of ONE session = sum of its own assistant messages' cost (the same\n // value the TUI shows as \"spent\"). Prefer session.get (runtime may expose\n // `cost`); fall back to summing messages for older servers.\n const sessionCost = async (sessionID: string): Promise<Spend> => {\n try {\n const res = await (client as any).session.get({ path: { id: sessionID } })\n const data = res?.data ?? res\n if (data && typeof data.cost === \"number\") {\n return {\n cost: data.cost,\n input: data.tokens?.input ?? 0,\n output: data.tokens?.output ?? 0,\n }\n }\n } catch {\n // fall through to the message sum\n }\n try {\n const res = await (client as any).session.messages({ path: { id: sessionID } })\n const data = res?.data ?? res\n const msgs: any[] = Array.isArray(data) ? data : (data?.messages ?? [])\n let cost = 0\n let input = 0\n let output = 0\n for (const m of msgs) {\n const info = m?.info ?? m\n if (!info || info.role !== \"assistant\") continue\n if (typeof info.cost === \"number\") cost += info.cost\n if (info.tokens) {\n input += info.tokens.input ?? 0\n output += info.tokens.output ?? 0\n }\n }\n return { cost, input, output }\n } catch {\n return { cost: 0, input: 0, output: 0 }\n }\n }\n\n // A failed/aborted child still burned tokens. Count its spend (if any) before\n // the session is deleted, so the running total stays honest.\n const accountWaste = async (parentID: string, childID: string | undefined): Promise<void> => {\n if (!childID) return\n try {\n const { cost } = await sessionCost(childID)\n if (cost > 0) {\n addSpend(parentID, cost)\n await log(\"info\", `delegate wasted cost on failed child ${childID}: ${money(cost)}`)\n }\n } catch {\n // never break cleanup over accounting\n }\n }\n\n // One compact line appended to every successful child report, so the root\n // model has the numbers it needs to reason about (and minimize) cost.\n const spendLine = async (parentID: string, childID: string, model: string): Promise<string> => {\n const [child, parent] = await Promise.all([sessionCost(childID), sessionCost(parentID)])\n const cumulative = addSpend(parentID, child.cost)\n return (\n `— cost · model ${model} · child ${money(child.cost)} (${num(child.input)} in / ${num(child.output)} out) · ` +\n `parent session spent ${money(parent.cost)} · delegated total this session ${money(cumulative)}`\n )\n }\n\n // ── child session ───────────────────────────────────────────────────────────\n // `candidates` are model refs; a null entry means \"no model override → inherit\n // the root model\" (this is what tier=standard does).\n\n // A custom tool must ask explicitly: the `permission` config key is consulted\n // only when the tool calls context.ask(...). Without this the gate is inert.\n //\n // `always: [\"*\"]` is load-bearing: when the user answers \"always\", opencode\n // persists ONLY the strings in `always` (Permission.reply -> iterates\n // existing.info.always) into the approved rules — `patterns` are only matched,\n // never remembered. An empty `always` therefore made every call ask again,\n // even after \"accept forever\". The built-in `task` tool uses the same [\"*\"].\n const askGate = async (\n context: any,\n permission: string,\n patterns: string[],\n metadata: Record<string, unknown>,\n ) => {\n if (typeof context?.ask !== \"function\") {\n await log(\"warn\", `tool context has no ask(); permission \"${permission}\" not enforced`)\n return\n }\n try {\n // opencode API drift: in current builds context.ask() returns a Promise,\n // older ones returned an Effect. Support both so the gate is never inert.\n const asked = context.ask({ permission, patterns, always: [\"*\"], metadata })\n if (asked && typeof (asked as any).then === \"function\") await asked\n else await Effect.runPromise(asked)\n } catch (e) {\n throw new Error(\n `Refused: permission \"${permission}\" not granted (${e instanceof Error ? e.message : String(e)})`,\n )\n }\n }\n\n const runChild = async (\n candidates: Array<string | null>,\n agent: string,\n brief: string,\n context: any,\n tier: Tier = \"standard\",\n ): Promise<any> => {\n await askGate(context, `delegate_${tier}_task`, [agent], {\n tier,\n agent,\n models: candidates.map((c) => c ?? \"inherit root model\"),\n })\n const tried: string[] = []\n for (const ref of candidates) {\n const target = ref ? splitRef(ref) : null\n if (ref && !target) {\n tried.push(`${ref}: bad model ref`)\n continue\n }\n const label = ref ?? \"standard (inherit root model)\"\n\n let sid: string | undefined\n try {\n const created = await (client as any).session.create({\n body: { parentID: context.sessionID, title: `delegate ${agent} · ${label}` },\n })\n const cdata = created?.data ?? created\n sid = cdata?.id\n if (!sid) {\n tried.push(`${label}: could not create child session`)\n continue\n }\n\n const body: any = { agent, parts: [{ type: \"text\", text: brief }] }\n if (target) body.model = target\n const res = await (client as any).session.prompt({ path: { id: sid }, body })\n const data = res?.data ?? res\n const err = res?.error ?? data?.info?.error\n if (err) {\n const msg = err?.message ?? err?.data?.message ?? JSON.stringify(err)\n tried.push(`${label}: ${msg}`)\n if (ref) dead.add(ref)\n await log(\"warn\", `delegate model failed, falling back: ${label} -> ${msg}`)\n await accountWaste(context.sessionID, sid)\n try {\n await (client as any).session.delete({ path: { id: sid } })\n } catch {\n // best-effort cleanup\n }\n continue\n }\n\n const report = extractReport(data)\n const spend = await spendLine(context.sessionID, sid, label)\n await log(\"info\", `delegate agent=${agent} model=${label} session=${sid} chars=${report.length} ${spend}`)\n return {\n output: `${report || \"(subagent returned no text)\"}\\n\\n${spend}`,\n // sessionId (lowercase d) is the key the TUI reads for its inline\n // subagent view; sessionID is kept for our own records.\n metadata: { agent, model: ref ?? \"inherit\", sessionID: sid, sessionId: sid },\n }\n } catch (e) {\n tried.push(`${label}: ${e}`)\n if (ref) dead.add(ref)\n await accountWaste(context.sessionID, sid)\n if (sid) {\n try {\n await (client as any).session.delete({ path: { id: sid } })\n } catch {\n // best-effort cleanup\n }\n }\n }\n }\n\n return `delegate failed:\\n${tried.join(\"\\n\")}\\nUse list_models to pick a working model, then pass it as 'model'.`\n }\n\n // Resolve the model(s) for a tier and run. standard inherits; simple/advanced use\n // the session pin or ask for one via the benchmark table.\n const runDelegation = async (tier: Tier, args: any, context: any): Promise<any> => {\n const agent = (args.agent || \"worker\").trim()\n const explicit = args.model?.trim()\n const models = await catalog()\n const available = [...models.keys()]\n\n if (explicit) {\n if (!models.has(explicit)) {\n return `ERROR: model \"${explicit}\" is not in the catalog. Use list_models.\\nAvailable:\\n${available.slice(0, 80).join(\"\\n\")}`\n }\n return await runChild([explicit], agent, args.brief, context, tier)\n }\n\n if (tier === \"standard\") return await runChild([null], agent, args.brief, context, tier)\n\n const pin = readTierPin(context.sessionID, tier)\n if (!pin) return await advise(tier, context.sessionID)\n\n const candidates: Array<string | null> = []\n if (models.has(pin.model) && !dead.has(pin.model)) candidates.push(pin.model)\n candidates.push(null) // fall back to inheriting the root model\n return await runChild(candidates, agent, args.brief, context, tier)\n }\n\n const delegateArgs = {\n brief: tool.schema\n .string()\n .describe(\n \"Complete, self-sufficient brief (task + DoD / context / contract / self-check / report format). The child sees no conversation history.\",\n ),\n agent: tool.schema.string().optional().describe(\"Subagent to run: worker | worker-lite | explore. Default worker.\"),\n model: tool.schema\n .string()\n .optional()\n .describe(\"Explicit model 'provider/model-id'. Wins over the tier; no fallback.\"),\n }\n\n const delegateTool = (tier: Tier, description: string) =>\n tool({\n description,\n args: delegateArgs,\n execute: async (args: any, context: any) => runDelegation(tier, args, context),\n })\n\n // ── tools ───────────────────────────────────────────────────────────────────\n\n return {\n tool: {\n delegate_simple_task: delegateTool(\n \"simple\",\n \"Run a subagent on a cheap model (tier 'simple') for easy/routine work to save money. On first use in a session it does NOT start a child — it returns MODEL SELECTION REQUIRED with a benchmark/price table until the user approves a model via set_tier_model. Returns only the child's final report.\",\n ),\n\n delegate_standard_task: delegateTool(\n \"standard\",\n \"Run a subagent that INHERITS the root/primary model (tier 'standard'). Note: a child starts with a fresh context (prompt-cache miss), so it still costs tokens, and by default this tool also asks for approval. Returns only the child's final report. Use when the work needs the root model's quality.\",\n ),\n\n delegate_advanced_task: delegateTool(\n \"advanced\",\n \"Run a subagent on a deliberately strong/expensive model (tier 'advanced') for hard logic where paying for intelligence is worth it. On first use in a session it returns MODEL SELECTION REQUIRED (a benchmark/price table) until the user approves a model via set_tier_model. Returns only the child's final report.\",\n ),\n\n list_models: tool({\n description:\n \"List available models with cost and context so you can choose an explicit model. Being listed does not guarantee authorization — if a model fails, delegate blacklists it and falls back.\",\n args: {\n provider: tool.schema.string().optional().describe(\"Provider id filter, e.g. opencode-go.\"),\n query: tool.schema.string().optional().describe(\"Substring filter on provider/model id.\"),\n limit: tool.schema.number().optional().describe(\"Max rows (default 40).\"),\n },\n execute: async (args: any) => {\n const models = await catalog()\n const providers: string[] = args.provider ? [args.provider] : routing.providers\n const q = args.query?.toLowerCase()\n const limit = Number.isFinite(args.limit) ? args.limit : 40\n const rows: string[] = []\n for (const [ref, m] of models) {\n if (providers.length && !providers.includes(m.providerID)) continue\n if (q && !ref.toLowerCase().includes(q)) continue\n const c = m.cost ?? {}\n const mark = dead.has(ref) ? \" [failed this session]\" : \"\"\n rows.push(`${ref}${mark} ctx=${m.context ?? \"?\"} cost in/out=${c.input ?? \"?\"}/${c.output ?? \"?\"}`)\n if (rows.length >= limit) break\n }\n return rows.length ? `available models:\\n${rows.join(\"\\n\")}` : \"no models matched\"\n },\n }),\n\n recommend_model: tool({\n description:\n \"Read-only: render the daily benchmark feed as a plain table (model, score, $/session, sessions/mo) plus your current root model as the baseline. No ranking, no formula — the root weighs price vs intelligence itself. Apply a choice with set_tier_model.\",\n args: {\n tier: tool.schema.string().optional().describe(\"simple | standard | advanced. Default standard.\"),\n refresh: tool.schema.boolean().optional().describe(\"Force re-fetch of the report instead of the 24h cache.\"),\n },\n execute: async (args: any, context: any) => {\n return await advise(tierOf(args.tier), context.sessionID, !!args.refresh)\n },\n }),\n\n set_tier_model: tool({\n description:\n \"Pin an approved model to a tier ('simple' or 'advanced') for THIS session, valid 24h, so the matching delegate tool can use it. Guarded by a native permission prompt (permission.set_tier_model = ask). Call only with a model the user agreed to. 'standard' inherits the root model and needs no pin.\",\n args: {\n tier: tool.schema.string().describe(\"simple | advanced (standard inherits the root model — no pin).\"),\n model: tool.schema.string().describe(\"Approved model 'provider/model-id', e.g. opencode-go/glm-5.3-flash.\"),\n note: tool.schema.string().optional().describe(\"Why this model for this tier.\"),\n },\n execute: async (args: any, context: any) => {\n const tier = tierOf(args.tier)\n const model = String(args.model ?? \"\").trim()\n if (tier === \"standard\") {\n return \"standard inherits the root model; no pin is needed. Pass tier=simple or tier=advanced to pin a model.\"\n }\n if (!model) return \"ERROR: model is required.\"\n const models = await catalog()\n if (!models.has(model)) {\n return `ERROR: \"${model}\" is not in the catalog. Use list_models.\\nAvailable:\\n${[...models.keys()].slice(0, 80).join(\"\\n\")}`\n }\n // Surface the overview AT the approval moment: the permission prompt carries\n // the chosen row plus the top MEASURED alternatives (same data as the advisor\n // table), so the human can judge without a separate lookup.\n const { table } = await buildTable(context.sessionID)\n const chosen = table.rows.find((r) => r.ref === model)\n const alternatives = alternativesDigest(table, model, 6)\n await askGate(context, \"set_tier_model\", [tier], {\n tier,\n model,\n note: args.note,\n chosen: chosen ? modelSummary(chosen) : `${model} (not in the benchmark feed)`,\n alternatives,\n })\n writeTierPin(context.sessionID, tier, model, args.note)\n await log(\"info\", `tier pinned: ${tier}=${model} session=${context.sessionID}`)\n const suffix = args.note ? `\\nNote: ${args.note}` : \"\"\n const rowsLine = alternatives.length\n ? `\\nTop measured alternatives at approval time:\\n${alternatives.map((a) => ` - ${a}`).join(\"\\n\")}`\n : \"\"\n return `Pinned tier \"${tier}\" → ${model} for this session (expires in ${routing.advisor.ttlHours}h). Re-run the matching delegate tool with the same brief.${suffix}${rowsLine}`\n },\n }),\n },\n }\n}\n~/.config/opencode/plugins/checkpoint-compaction.ts.disabledLegacy plugin, predecessor of the sentinel. Present in the original as .disabled (both override the same compaction prompt — they cannot be enabled together; the STATE.md write behavior is absorbed by the sentinel). Can be omitted for a new project; included here for structural accuracy.
// checkpoint-compaction.ts\n// Global opencode plugin.\n//\n// Replaces opencode's default compaction summary prompt with a soft\n// \"write a checkpoint\" prompt, so an auto-compaction produces a memory the\n// next turn can actually continue from:\n// 1. what was done (completed work, decisions, task state)\n// 2. what to do next (immediate steps / plan)\n// 3. the human's standing preferences and instructions (as said)\n//\n// ---------------------------------------------------------------------------\n// HOW TO KILL THIS PLUGIN:\n// Quick off: export OPENCODE_CHECKPOINT_OFF=1 then restart opencode.\n// Emergency: export OPENCODE_PURE=1 then restart opencode.\n// Permanent: delete the \"plugin\" entry + this file + restart.\n// ---------------------------------------------------------------------------\n\nimport * as fs from \"node:fs\"\nimport * as path from \"node:path\"\nimport { fileURLToPath } from \"node:url\"\n\nconst PLUGIN_NAME = \"checkpoint-compaction\"\nconst DISABLED = process.env.OPENCODE_CHECKPOINT_OFF === \"1\"\n\nfunction logFile() {\n try {\n return path.join(path.dirname(fileURLToPath(import.meta.url)), `${PLUGIN_NAME}.log`)\n } catch {\n return path.join(process.env.TEMP || \"/tmp\", `${PLUGIN_NAME}.log`)\n }\n}\n\nfunction log(message) {\n try {\n const line = `[${new Date().toISOString()}] ${message}\\n`\n fs.appendFileSync(logFile(), line)\n } catch {\n // logging must never throw\n }\n}\n\nconst BASE_PROMPT = `You are asked to write a session checkpoint instead of a plain summary.\nProduce ONE structured checkpoint that will serve as the whole memory of this\nconversation after it is compacted. The next turn starts from this text alone\nand has no other memory, so be dense, concrete and complete. It must contain,\nin this order:\n\n1. What was done — completed work, decisions taken, key state of the task.\n Concrete, not vague: name the actual steps and results.\n2. What to do next — the immediate next steps and the plan the next turn\n should follow.\n3. Human's preferences and instructions — a dedicated bullet list of every\n standing preference, order and instruction the human gave during this\n session, stated as the human said them (keep the wording close to the\n original). This list is mandatory even when it overlaps with the steps\n above.\n\nWrite the checkpoint in the language the human used in this session. Do not\nask questions. Do not mention compaction or summarize that this is a summary.`\n\nfunction findGuideSection(agentsText) {\n const lines = agentsText.split(\"\\n\")\n let start = -1\n let end = -1\n for (let i = 0; i < lines.length; i++) {\n const l = lines[i]\n if (l.includes(\"STATE.md\") || /checkpoint/i.test(l)) {\n for (let j = i; j >= 0; j--) {\n if (/^#{1,4}\\s/.test(lines[j])) {\n start = j\n break\n }\n }\n if (start < 0) start = i\n end = i\n for (let j = i + 1; j < lines.length; j++) {\n if (/^#{1,4}\\s/.test(lines[j])) {\n end = j\n break\n }\n }\n break\n }\n }\n if (start < 0) return \"\"\n const stop = end > i ? end : start + Math.max(20, i - start + 12)\n return lines.slice(start, Math.min(lines.length, stop)).join(\"\\n\").trim()\n}\n\nfunction readProjectGuide(directory) {\n try {\n const p = path.join(directory, \"AGENTS.md\")\n if (!fs.existsSync(p)) return \"\"\n const section = findGuideSection(fs.readFileSync(p, \"utf8\"))\n return section.length > 1600 ? section.slice(0, 1600) : section\n } catch {\n return \"\"\n }\n}\n\nfunction buildPrompt(directory) {\n const guide = readProjectGuide(directory)\n if (!guide) return BASE_PROMPT\n return `${BASE_PROMPT}\\n\\nThe project's checkpoint rules (from AGENTS.md) to follow when you write the checkpoint:\\n${guide}`\n}\n\nasync function sessionDirectory(client, sessionID) {\n try {\n const res = await client.session.get({ sessionID })\n const session = res?.data ?? res\n return session?.directory || null\n } catch (err) {\n log(`ERROR session.get failed for ${sessionID}: ${err?.message || err}`)\n return null\n }\n}\n\nasync function lastSummary(client, sessionID) {\n try {\n const res = await client.session.messages({ sessionID })\n const list = res?.data ?? res\n if (!Array.isArray(list)) return null\n for (let i = list.length - 1; i >= 0; i--) {\n const item = list[i]\n if (item?.info?.summary !== true) continue\n const text = (item.parts || [])\n .filter((p) => p?.type === \"text\")\n .map((p) => p?.text || \"\")\n .join(\"\\n\")\n .trim()\n if (text) return text\n }\n return null\n } catch (err) {\n log(`ERROR session.messages failed for ${sessionID}: ${err?.message || err}`)\n return null\n }\n}\n\nfunction writeStateCheckpoint(directory, text) {\n const statePath = path.join(directory, \"STATE.md\")\n if (!fs.existsSync(statePath)) {\n log(`SKIP no STATE.md at ${statePath}`)\n return\n }\n const stamp = new Date().toISOString().slice(0, 16).replace(\"T\", \" \")\n const block = `\\n## Checkpoint (auto-compaction, ${stamp})\\n${text.trim()}\\n`\n try {\n const content = fs.readFileSync(statePath, \"utf8\")\n const marker = \"<!-- ARCHIVE:BELOW -->\"\n const idx = content.indexOf(marker)\n const updated =\n idx >= 0 ? content.slice(0, idx) + block + \"\\n\" + content.slice(idx) : content + block\n fs.writeFileSync(statePath, updated)\n log(`WRITE checkpoint (${text.trim().length} chars) -> ${statePath}`)\n } catch (err) {\n log(`ERROR cannot write STATE.md ${statePath}: ${err?.message || err}`)\n }\n}\n\nexport default async ({ client }) => {\n if (DISABLED) {\n log(\"LOADED in DISABLED mode (OPENCODE_CHECKPOINT_OFF=1); doing nothing\")\n return {}\n }\n log(\"LOADED checkpoint-compaction plugin (active)\")\n return {\n async \"experimental.session.compacting\"(input, output) {\n try {\n const sessionID = input?.sessionID\n let directory = null\n if (sessionID) directory = await sessionDirectory(client, sessionID)\n if (output) {\n output.prompt = buildPrompt(directory)\n log(\n `HOOK session.compacting session=${sessionID} dir=${directory} prompt_chars=${output.prompt.length}`,\n )\n }\n } catch (err) {\n log(`ERROR session.compacting hook: ${err?.message || err}`)\n }\n },\n async event({ event: { type, properties } }) {\n try {\n const sessionID = properties?.sessionID\n if (!sessionID) return\n let text = null\n if (type === \"session.next.compaction.ended\") {\n text = properties?.text || null\n } else if (type === \"session.compacted\") {\n text = await lastSummary(client, sessionID)\n }\n if (!text) return\n const directory = await sessionDirectory(client, sessionID)\n log(`EVENT ${type} session=${sessionID} chars=${text.trim().length}`)\n if (directory) writeStateCheckpoint(directory, text)\n } catch (err) {\n log(`ERROR event hook: ${err?.message || err}`)\n }\n },\n }\n}\n~/.config/opencode/templates/delegation-mode.mdMaster copy. Enabling in a project = appending the ## DELEGATION MODE section to <project>/AGENTS.md (or keeping it in <project>/AGENTS/delegation-mode.md with a pointer from AGENTS.md).
<!--\n CANONICAL DELEGATION-MODE ADDENDUM (master copy) - source of truth.\n To enable delegation in a project, append the \"## DELEGATION MODE\" section\n below to <project>/AGENTS.md, or keep it in <project>/AGENTS/delegation-mode.md\n with a pointer from AGENTS.md. Opt-in per project; NOT auto-loaded globally.\n Runbook: ~/.config/opencode/README.md §4. Safe to copy/edit per project.\n Regenerate = copy this file's section.\n\n Consumers of the section (add a line on adoption; keep the carried revision honest):\n | project | carries it as | lang | revision |\n |----------|---------------------------|------|----------|\n | <projA> | AGENTS/delegation-mode.md | en | r1 |\n | <projB> | AGENTS/delegation-mode.md | ru | r1 |\n\n BREAKING CHANGE RULE: a change that alters the section's meaning (tool names,\n tier flow, gates, limits) bumps `Section revision` and MUST be listed here;\n every consumer is notified and ports/regenerates it BEFORE the change is relied upon.\n-->\n## DELEGATION MODE — delegation workflow for heavy tasks\n\n> Section revision: **r1**. Carried by every consumer copy; bump it on a breaking\n> change and update the consumers list in the master header.\n\n> **Scope: the primary (root) session only.** Subagents (`worker`, `worker-lite`,\n> `explore`) MUST ignore this section entirely and just execute their brief. The user\n> does not switch them.\n\n**Enable.** The user writes one of: \"let's work in delegation mode\", \"delegation mode\",\n\"delegate to subagent\", \"work via subagent\", \"delegation mode\".\nOnce enabled — **do not ask again**, confirm in one line (\"Delegation mode on\") and\nfollow the protocol below until the task is done.\n\n**Disable.** The user writes: \"turn off delegation\", \"work directly\",\n\"without delegation\" — then work as usual.\n\nIn this mode the primary model is the **orchestrator**: it explores, keeps the vision,\nwrites precise briefs and verifies results. It **does not write code or do routine\nwork itself** — all execution goes to a subagent. Goal: preserve the root context\n(the valuable vision) and survive compaction.\n\n### Roles\n| who | tier when delegating | does |\n|-----|--------|------|\n| root (me) | — (session primary model) | recon, synthesis, briefs, verification, decisions. Writes no code. |\n| `explore` | `simple` (read-only, cheap) | recon: find/read/collect facts, read-only |\n| `worker` | `standard` (inherits the root model) | main implementation of one coherent step |\n| `worker-lite` | `standard` (use `simple` for routine) | mechanical/simple edits |\n\nModels are baked into NEITHER the agent files NOR the tiers — the root picks the\nconcrete model with the user's approval through `delegate` (see \"Model selection\").\nChanging or removing a model never breaks the agents.\n\n### Cycle (strictly sequential, one subagent at a time)\n1. **Recon.** Minimal reading in root. Delegate broad search to `explore`. Synthesis,\n decisions and the \"vision\" stay in root.\n2. **Brief.** Write a self-sufficient brief using the template below and launch **one**\n subagent via the matching tool: `delegate_standard_task` (inherits the root model,\n default), `delegate_simple_task` (cheaper), or `delegate_advanced_task` (smarter).\n Pass `agent` (`worker` / `worker-lite` / `explore`). If the simple/advanced tool has\n no approved model for this session yet, the call returns `MODEL SELECTION REQUIRED`\n with a table — choose a model with approval (see \"Model selection\") and repeat the\n call with the same brief.\n3. **Execution.** The subagent works in its own context, self-checks and returns a\n short report. Its log and noise do **not** enter the root context.\n4. **Verification.** Root verifies the critical bits: tests, commands, key diffs. Not\n done — extend the brief and rerun the subagent for the same logical step.\n5. **Record.** Important facts/paths/decisions go to `STATE.md` or `JOURNAL.md`. Keep\n the path in context, not the contents.\n6. Repeat until the task is done. End with a short summary for the user.\n\n### Model selection (delegate tools + advisor)\nThe native `task` cannot change a subagent's model, so we delegate through the\nprimary-only delegate tools (plugin `~/.config/opencode/plugins/delegate.ts`):\n`delegate_simple_task`, `delegate_standard_task`, `delegate_advanced_task`. One tool\nper tier, because opencode's permission is keyed by tool name — so the user can set a\ndifferent policy per tier (e.g. auto-approve simple, approve standard/advanced by hand).\n\n**Tiers are only a hint about the price/intelligence appetite — no models baked in:**\n- `standard` (default) — the child inherits the root model (no model choice).\n- `simple` — \"cheaper\": read-only / routine.\n- `advanced` — \"do not be afraid to pay for intelligence\": hard logic.\n\nNote: a child always starts with a FRESH context (prompt-cache miss), so **every**\ndelegation costs tokens — all three tools ask for approval by default. The user may set\nany of them to `\"allow\"` (accept forever) in `opencode.jsonc`.\n\n**Session pin (24h) with human approval.** For simple/advanced the advisor pulls the\ndaily benchmark feed and renders a **plain table** (model, score, $/session,\nsessions/mo) split into **MEASURED** rows and a **NO BENCHMARK** block, plus the\nbaseline = your current root model, so the root can judge simple/advanced RELATIVE\nto it. No formulas, no thresholds, no \"best model\". A score-less model cannot be\nweighed on intelligence: **do not pin one as the tier representative** unless there\nis an explicit non-benchmark reason.\n1. Calling `delegate_simple_task` / `delegate_advanced_task` with no approved model\n **does not start a subagent**; it returns `MODEL SELECTION REQUIRED` with the table.\n2. Root **shows the table to the user**, then — from the MEASURED rows, weighing price\n vs intelligence against the baseline and its own knowledge — proposes **one**\n concrete model; the user may name **any other** model.\n3. Root calls `set_tier_model({ tier: \"simple\" | \"advanced\", model, note })` —\n opencode shows a **native permission prompt** that lists the top measured\n alternatives, and the model is pinned only after the human approves.\n4. Root repeats the same delegate tool with the same brief — the subagent runs.\n\nThe pin lives 24h **within the session**. While it is fresh, the delegate tool uses it\nautomatically. To change it — call `set_tier_model` again (approval again).\n\n- `delegate_standard_task` — inherit the root model (default; still asks by default).\n- `delegate_simple_task` / `delegate_advanced_task` — the model pinned to this\n session's tier, or `MODEL SELECTION REQUIRED`.\n- `model: \"<provider>/<model-id>\"` — explicit model on any delegate tool (wins over\n the tier; manual override).\n- `recommend_model({ tier })` — show the table any time without starting a child.\n- `list_models` — the live catalog with cost/context, if you need to name your own.\n\nThe advisor **never applies a model itself** and never ranks: it only shows data. If\nthe feed is unavailable (offline, no cache) the table degrades to a `list_models`\nhint, but the child still does not start without an approved/explicit model.\n\nIf a pinned model is unavailable (Forbidden/disabled), the delegate tool marks it dead\nand falls back to `standard` (inheritance). An explicit `model` returns the error text\non failure — check `list_models` and retry.\n\n### Brief template (root writes it BEFORE launch; the subagent sees no history)\nTASK — one coherent step + Definition of Done\nCONTEXT — file paths, facts, decisions (what it needs and what it does not know)\nCONTRACT — which files may/may not be touched, style, what NOT to do\nSELF-CHECK — how it will verify it is done\nREPORT — <=60 lines: DONE / FILES(path:lines) / DECISIONS / NOT DONE & RISKS;\ndo NOT paste whole files\n\n### Context discipline (the whole point of the mode)\n- Root does not read files in bulk — targeted reads or via `explore`.\n- **Balance root-context protection against the child's startup cost.** The mode exists\n to keep the root context alive (delay compaction) across a heavy task; the price is a\n fresh context (prompt-cache miss) for every child. Weigh per step: a trivial edit\n barely protects the root context and still pays a full child startup, so the root does\n it; a self-contained step heavy enough to bloat or risk the root context goes to a\n child. Both extremes — delegate everything, delegate nothing — lose.\n- The subagent's report is short; full output and logs stay in its session.\n- Large results go to a file; only the path enters context.\n- One subagent at a time, no parallel runs.\n- On a context-sentinel warning (70%/85%) — update the checkpoint\n (`STATE.md`/`CHECKPOINT*.md`) first, then `/compact`.\n\n### Subagent failure\nIf a subagent lacks data it returns a **BLOCKER**, not guesses. Root resolves the\nblocker, fixes the brief and relaunches. If a step does not fit `steps: 80`, split the\nstep — do not raise the limit.\n\n### Subagent routing\n- Logic, architecture, hard edits → `worker`\n- Mechanical routine, simple edits → `worker-lite`\n- Read-only search/recon → `explore`\n- Unsure → `worker`\n~/.config/opencode/README.md (runbook)# opencode global config – runbook\n\nGlobal config root: `~/.config/opencode/` (Windows: `C:\\Users\\<you>\\.config\\opencode\\`).\nAll changes take effect only after **restarting opencode**.\n\n## Layout\n| Path | What |\n|------|------|\n| `opencode.jsonc` | model, small_model, plugins, effective context cap, compaction, primary_tools |\n| `routing.json` | providers filter + advisor (benchmark feed) |\n| `plugins/context-sentinel.ts` | custom compaction + mechanical checkpoint file + context warning + signing |\n| `plugins/delegate.ts` | primary-only tools `delegate_*` + `list_models` + `recommend_model` + `set_tier_model` |\n| `plugins/checkpoint-compaction.ts.disabled` | previous plugin, retired (see §1) |\n| `agents/worker.md` | subagent: coherent implementation step (no model → inherits primary) |\n| `agents/worker-lite.md` | subagent: routine edits (model chosen per call via delegate/tier) |\n| `agents/explore.md` | read-only recon subagent |\n| `lib/advisor-core.ts` | pure helpers of the advisor (NOT a plugin module) |\n| `templates/delegation-mode.md` | master copy of the DELEGATION MODE addendum |\n| `skills/<name>/SKILL.md` | task flows: always-on is only the catalog (name + description); the body loads when the skill is invoked |\n| `command/<name>.md` | thin slash-command that forces a skill load (`$ARGUMENTS`); see the `dump` pattern |\n| `tests/` | node:test suites for `advisor` and `context-sentinel` |\n\nProject switch for delegation lives in each project's `AGENTS.md` (or `AGENTS/delegation-mode.md` with a pointer), not here.\n\n## 0. Lazy layers (keep the always-on digest small)\n\nAgent startup = base prompt + compact summary + the root `AGENTS.md`. Everything else is\nloaded only when needed:\n\n- **Area rules** — a nested `AGENTS.md` (e.g. `packages/<pkg>/AGENTS.md`) is auto-injected\n by opencode as a `<system-reminder>` when an agent `read`s a file under that path\n (read-triggered only — `grep`/`glob`/`write` do NOT trigger it). Repo-wide rules stay in\n the root digest; package-scoped rules move to the package file.\n- **Task flows (skills)** — `.opencode/skills/<name>/SKILL.md` in a project (or\n `skills/<name>/SKILL.md` globally). Only `name` + `description` are always-on; the body\n enters context when the skill is invoked.\n- **Commands** — `.opencode/command/<name>.md` defines a slash-command. A thin command whose\n body says \"call the skill tool with name X\" reliably forces a skill load; `$ARGUMENTS` is\n substituted. This is how a task flow is made discoverable without bloating the digest.\n\nRule of thumb: what is read at startup must not grow; only what is read on demand grows.\n\n## 1. Compaction + context sentinel (v1.5.0)\n`plugins/context-sentinel.ts`, referenced explicitly from `opencode.jsonc` `plugin: [...]`.\n1. Reads prompt tokens of the last assistant message (`input + cache.read + cache.write`)\n and warns via TUI toast at `SENTINEL_WARN` (0.7) / `SENTINEL_CRIT` (0.85) of the\n **effective** context limit (§2). Subagent (child) sessions are tracked via\n `session.created`/`session.updated` and ignored, so a delegate's context never\n triggers a root warning.\n2. Replaces the stock compaction prompt with: TASK / **USER INSTRUCTIONS (verbatim)** /\n STATUS / KEY FACTS & DECISIONS / **ALREADY ESTABLISHED (DO NOT RE-EXPLORE)** /\n FILES TOUCHED / NEXT STEPS / CHECKPOINTS & DOCS, and **forbids tool calls** in the\n compaction reply (the model must output text only).\n3. **Model-independent mechanical checkpoint.** In `session.compacting` the plugin\n writes `<project>/.opencode/CHECKPOINT-<stamp>.md` with the last `SENTINEL_KEEP_USER`\n (12) user posts **verbatim**, the session todo list and the files touched by tool\n calls. The path is pushed into `output.context`; the same verbatim block is appended\n to the prompt so the digest cannot drop the user's own words. The file is written\n even if the compaction model fails completely.\n4. **Digest validation + fallback.** After `session.compacted`, a model digest is stored\n only if it is real prose (≥ `SENTINEL_MIN_DIGEST` chars, no tool-call syntax); it is\n appended under `## MODEL DIGEST`. Otherwise the mechanical file stays authoritative\n and a `warn` is logged (no more silent failure).\n5. Signs newly written `CHECKPOINT*` / `*.checkpoint.md` files.\n6. `experimental.compaction.autocontinue`: the synthetic auto-continue runs only when a\n checkpoint file exists; otherwise it is disabled. If `STATE.md` exists, the validated\n digest is also appended there BELOW `<!-- ARCHIVE:BELOW -->` (the head stays the agent's\n current checkpoint, not a chronicle). Child compactions are ignored.\n\nLimits resolve live from `/config/providers`, then `config.get()`, then\n`opencode.jsonc`, then fallback `128000`. Env: `SENTINEL_WARN`, `SENTINEL_CRIT`,\n`SENTINEL_SIGN`, `SENTINEL_CHECKPOINT_DIR` (default `.opencode`), `SENTINEL_KEEP_USER`\n(12), `SENTINEL_MIN_DIGEST` (200). Unit tests: `tests/context-sentinel.test.mjs`.\nKill-switch: `mv ~/.config/opencode/plugins/context-sentinel.ts{,.disabled}` + restart\n(also drop it from `plugin[]` to remove permanently). The old `checkpoint-compaction.ts`\nis disabled because both override the same compacting prompt; its STATE.md behavior is\nfolded in.\n\n## 2. Effective context cap (why 250k, not 1M)\nA model may support a huge context, but quality/latency/pricing typically degrade around\n200–250k, so `opencode.jsonc` overrides the built-in limit:\n```jsonc\n\"provider\": { \"<provider>\": { \"models\": {\n \"<root-model>\": { \"limit\": { \"context\": 250000, \"output\": 64000 } }\n}}}\nIt deep-merges (tool-call/status/cost preserved) and /config/providers then reports the\ncapped value. output < context so the reserve can't exceed the window.\ncompaction: { auto, reserved: 16000, preserve_recent_tokens: 30000 } keeps the last\n~30k raw tokens verbatim across compaction. Revert = delete the provider block.
plugins/delegate.ts)Primary-only tools (subagents get them denied via experimental.primary_tools). A child\nsession always starts with a fresh context (prompt-cache miss), so every delegation\ncosts tokens — hence all tiers ask by default (see the permission block).
| tool | \nmodel? | \nwhat | \n
|---|---|---|
| delegate_standard_task | \ninherits root | \nrun a child on the root model (no model choice) | \n
| delegate_simple_task | \npinned | \ncheaper tier, for routine work | \n
| delegate_advanced_task | \npinned | \nsmarter/pricier tier, for hard logic | \n
| set_tier_model({ tier, model, note }) | \n— | \npin a model to simple / advanced for the session (24h) | \n
| recommend_model({ tier }) | \n— | \nshow the benchmark/price table + your root model as baseline | \n
| list_models({ provider?, query?, limit? }) | \n— | \nlive catalog with cost/context | \n
How a simple/advanced call resolves:
model: \"provider/model-id\" on the delegate tool wins (no fallback);set_tier_model, 24h);MODEL SELECTION REQUIRED with a plain table (model, score, $/session,\nsessions/mo) split into MEASURED rows and a NO BENCHMARK block + the root model\nas baseline — the root shows the table, proposes ONE measured model, the user approves,\nthen the same brief is re-sent. A score-less model is not to be proposed as the tier\nrepresentative;standard (inheritance).The advisor only shows data (no ranking, no auto-apply). Agent files carry no model,\nso nothing is load-bearing. routing.json: providers + advisor (enabled,\nreportUrl, ttlHours, maxRows). No tier→model chains are baked in — the model is\nchosen per session with approval.
Money gate — why the permission block works. A plugin tool is NOT gated by merely\nlisting its name in permission. opencode consults permission[<name>] only when the tool's\nexecute calls ctx.ask({ permission: \"<name>\", patterns, always, metadata }) (ctx = the\ntool's ToolContext). delegate_*_task and set_tier_model do this, so their ask rules\nfire; without the ctx.ask call the gate is silent. always: [\"*\"] is load-bearing: on the\n\"always\" reply opencode persists only the always patterns (not patterns), so an empty\narray re-asked on every call. ctx.ask() returns an Effect in this build (older builds a\nPromise) — the gate supports both. set_tier_model also passes the chosen row + top measured\nalternatives in metadata, so the approval prompt carries the same overview the advisor shows.
Kill-switch: mv ~/.config/opencode/plugins/delegate.ts{,.disabled}, remove it from\nplugin[], drop experimental.primary_tools + the permission block, then restart.
Cost accounting. A child session's spend never rolls into the parent's session.cost\n(the server increments it only for the session where a step finishes), so the delegate\nplugin surfaces both numbers itself: every successful child report carries a\n— cost · model … · child … · parent session spent … · delegated total this session …\nline, and a failed/aborted child still accounts its burned tokens before cleanup. This lets\nthe orchestrator budget and prefer cheaper delegation.
Opt-in per project. The canonical addendum is templates/delegation-mode.md\n(master copy). To enable it in a project, append its ## DELEGATION MODE section to\n<project>/AGENTS.md, or keep it in <project>/AGENTS/delegation-mode.md with a pointer\nfrom AGENTS.md (so subagents, which must ignore it, do not load it at startup). The\nsection is NOT auto-loaded from the global config.
Activate by saying: «let's work in delegation mode», «delegation mode»,\n«delegate to subagent», «work via subagent», «delegation mode». Deactivate:\n«turn off delegation», «work directly», «without delegation». The root then only\nresearches, writes briefs and verifies; execution goes through the delegate tools (§3);\nsubagents ignore the section entirely.
\nBrief template (root writes it BEFORE launch; the child sees no history):
\n1. TASK — one coherent step + Definition of Done\n2. CONTEXT — file paths, facts, decisions (what it needs and what it does not know)\n3. CONTRACT — which files may/may not be touched, style, what NOT to do\n4. SELF-CHECK — how it will verify it is done\n5. REPORT — <=60 lines: DONE / FILES(path:lines) / DECISIONS / NOT DONE & RISKS\nBeing listed ≠ authorized: delegate treats a call failure as authoritative and falls\nback. Verify each candidate by actually calling it with a trivial prompt, then record:
| model | \nworks? | \ncost in/out | \nnote | \n
|---|---|---|---|
| / | \n? | \n? | \nmain; real ctx ?; capped (§2) | \n
| / | \n? | \n? | \nsmall_model + cheap tier | \n
| … | \n\n | \n | \n |
small_model must be the cheapest WORKING model. A model answering Forbidden or\nModel is disabled must not be referenced anywhere.
\n### 3.13 `~/.config/opencode/tests/advisor.test.mjs`\n\n```javascript\nimport { test } from \"node:test\"\nimport assert from \"node:assert/strict\"\nimport {\n normalizeName,\n variantOf,\n isPeakNow,\n effectiveRow,\n mapRowToRef,\n tierOf,\n modelTable,\n tableText,\n alternativesDigest,\n modelSummary,\n} from \"../lib/advisor-core.ts\"\n\nconst PEAK = { tz: \"UTC\", days: [1, 5], ranges: [[1, 0, 4, 0], [6, 0, 10, 0]] }\n\ntest(\"normalizeName slugifies tariff names, strips parentheticals\", () => {\n const cases = {\n \"GLM-5.3-Flash\": \"glm-5.3-flash\",\n \"GLM-5.3\": \"glm-5.3\",\n \"DeepSeek V4.1 Flash (Off-Peak)\": \"deepseek-v4.1-flash\",\n \"DeepSeek V4.1 Flash (Peak)\": \"deepseek-v4.1-flash\",\n \"Qwen3.7 Plus (≤ 256K tokens)\": \"qwen3.7-plus\",\n \"GPT 5.6 Luna (> 272K tokens)\": \"gpt-5.6-luna\",\n \"MiMo V2.5\": \"mimo-v2.5\",\n \"MiniMax M3\": \"minimax-m3\",\n \"Muse Spark 1.3 Contributor\": \"muse-spark-1.3-contributor\",\n \"\": \"\",\n }\n for (const [input, expected] of Object.entries(cases)) {\n assert.equal(normalizeName(input), expected, `normalizeName(${JSON.stringify(input)})`)\n }\n assert.equal(normalizeName(null), \"\")\n assert.equal(normalizeName(undefined), \"\")\n})\n\ntest(\"variantOf distinguishes peak / off-peak / none\", () => {\n assert.equal(variantOf(\"DeepSeek V4.1 Flash (Off-Peak)\"), \"off\")\n assert.equal(variantOf(\"DeepSeek V4.1 Flash (Peak)\"), \"peak\")\n assert.equal(variantOf(\"GLM-5.3-Flash\"), null)\n assert.equal(variantOf(null), null)\n})\n\ntest(\"isPeakNow follows the feed hours (Mon-Fri 01-04 & 06-10 UTC)\", () => {\n const fri = new Date(Date.UTC(2026, 8, 11, 2, 0))\n assert.equal(fri.getUTCDay(), 5, \"2026-09-11 must be a Friday\")\n assert.equal(isPeakNow(PEAK, new Date(Date.UTC(2026, 8, 11, 2, 0))), true, \"Fri 02:00 peak\")\n assert.equal(isPeakNow(PEAK, new Date(Date.UTC(2026, 8, 11, 7, 0))), true, \"Fri 07:00 peak\")\n assert.equal(isPeakNow(PEAK, new Date(Date.UTC(2026, 8, 11, 0, 30))), false, \"Fri 00:30 off\")\n assert.equal(isPeakNow(PEAK, new Date(Date.UTC(2026, 8, 11, 5, 0))), false, \"Fri 05:00 off\")\n assert.equal(isPeakNow(PEAK, new Date(Date.UTC(2026, 8, 12, 2, 0))), false, \"Sat 02:00 off\")\n assert.equal(isPeakNow(null, fri), false, \"no windows = never peak\")\n})\n\ntest(\"effectiveRow picks the live peak/off-peak variant\", () => {\n const rows = [\n { model: \"DeepSeek V4.1 Flash (Off-Peak)\", score: 88, mpPerSession: 11.9, peakHours: PEAK },\n { model: \"DeepSeek V4.1 Flash (Peak)\", score: 88, mpPerSession: 23.79, peakHours: PEAK },\n ]\n assert.equal(effectiveRow(rows, new Date(Date.UTC(2026, 8, 11, 2, 0))).mpPerSession, 23.79)\n assert.equal(effectiveRow(rows, new Date(Date.UTC(2026, 8, 11, 5, 0))).mpPerSession, 11.9)\n assert.equal(effectiveRow([rows[0]], new Date(Date.UTC(2026, 8, 11, 2, 0))).mpPerSession, 11.9)\n assert.equal(effectiveRow([], new Date()), null)\n})\n\ntest(\"mapRowToRef prefers stable modelId, else normalizes the display name\", () => {\n const catalog = [\"opencode-go/glm-5.3-flash\", \"opencode-go/deepseek-v4.1-flash\", \"other/x\"]\n assert.equal(mapRowToRef({ modelId: \"glm-5.3-flash\", provider: \"opencode-go\" }, catalog, [\"opencode-go\"]), \"opencode-go/glm-5.3-flash\")\n assert.equal(mapRowToRef({ model: \"DeepSeek V4.1 Flash (Off-Peak)\" }, catalog, [\"opencode-go\"]), \"opencode-go/deepseek-v4.1-flash\")\n assert.equal(mapRowToRef({ model: \"Nonexistent\" }, catalog, [\"opencode-go\"]), null)\n})\n\ntest(\"tierOf maps aliases and unknown values\", () => {\n assert.equal(tierOf(\"simple\"), \"simple\")\n assert.equal(tierOf(\"low\"), \"simple\", \"low is an alias of simple\")\n assert.equal(tierOf(\"ADVANCED\"), \"advanced\")\n assert.equal(tierOf(\"standard\"), \"standard\")\n assert.equal(tierOf(\"\"), \"standard\")\n assert.equal(tierOf(\"high\"), \"standard\")\n assert.equal(tierOf(undefined), \"standard\")\n})\n\nconst report = {\n generatedAt: \"2026-09-11T00:00:00Z\",\n rows: [\n { model: \"Mid\", score: 85, priceUsdPerSession: 0.002, mpPerSession: 20, requestsPerMonth: 5000, quotaUsd: 60, peakHours: null },\n { model: \"Cheap Small\", score: 70, priceUsdPerSession: 0.001, mpPerSession: 10, requestsPerMonth: 10000, quotaUsd: 60, peakHours: null },\n { model: \"Beast\", score: 95, priceUsdPerSession: 0.05, mpPerSession: 500, requestsPerMonth: 200, quotaUsd: 60, peakHours: null },\n { model: \"Unmeasured\", score: null, priceUsdPerSession: 0.0005, mpPerSession: 5, requestsPerMonth: 20000, quotaUsd: 60, peakHours: null },\n ],\n}\n\ntest(\"modelTable lists every live model with raw score/price (measured first, then cheapest)\", () => {\n const catalog = [\"opencode-go/cheap-small\", \"opencode-go/mid\", \"opencode-go/beast\", \"opencode-go/unmeasured\"]\n const t = modelTable({ report, fetchedAt: Date.now(), stale: false, catalog, dead: new Set(), providers: [\"opencode-go\"], rootRef: \"opencode-go/mid\" })\n assert.deepEqual(\n t.rows.map((r) => r.ref),\n [\"opencode-go/cheap-small\", \"opencode-go/mid\", \"opencode-go/beast\", \"opencode-go/unmeasured\"],\n \"measured models first (cheapest first), score-less rows last\",\n )\n assert.equal(t.report.measured, 3, \"three models have a score\")\n assert.equal(t.report.total, 4)\n assert.equal(t.rows.find((r) => r.ref === \"opencode-go/unmeasured\").score, null, \"unmeasured kept with score null\")\n assert.equal(t.rows.find((r) => r.ref === \"opencode-go/unmeasured\").measured, false)\n assert.equal(t.rows.find((r) => r.ref === \"opencode-go/mid\").measured, true)\n assert.equal(t.rows.find((r) => r.ref === \"opencode-go/mid\").root, true, \"root model flagged as baseline\")\n assert.equal(t.rows.filter((r) => r.root).length, 1)\n})\n\ntest(\"modelTable collapses peak/off variants and drops dead/missing\", () => {\n const rep = {\n generatedAt: \"x\",\n rows: [\n { model: \"DeepSeek V4.1 Flash (Off-Peak)\", score: 88, priceUsdPerSession: 0.01, mpPerSession: 11.9, requestsPerMonth: 8400, quotaUsd: 60, peakHours: PEAK },\n { model: \"DeepSeek V4.1 Flash (Peak)\", score: 88, priceUsdPerSession: 0.02, mpPerSession: 23.79, requestsPerMonth: 4200, quotaUsd: 60, peakHours: PEAK },\n ],\n }\n const catalog = [\"opencode-go/deepseek-v4.1-flash\", \"opencode-go/mid\"]\n const t = modelTable({ report: rep, fetchedAt: Date.now(), stale: false, catalog, dead: new Set([\"opencode-go/mid\"]), providers: [\"opencode-go\"] })\n assert.equal(t.rows.length, 1, \"peak/off collapsed into one row\")\n assert.equal(t.rows[0].ref, \"opencode-go/deepseek-v4.1-flash\")\n})\n\ntest(\"modelTable returns a reason and no rows without a report\", () => {\n const t = modelTable({ report: null, fetchedAt: 0, stale: false, catalog: [], dead: new Set(), providers: [] })\n assert.equal(t.rows.length, 0)\n assert.equal(t.reason, \"no report\")\n assert.match(tableText(t, \"low\"), /feed unavailable/i)\n})\n\ntest(\"tableText renders a table with a baseline and tells the root to decide, not to use a formula\", () => {\n const catalog = [\"opencode-go/cheap-small\", \"opencode-go/mid\"]\n const t = modelTable({ report, fetchedAt: Date.now(), stale: false, catalog, dead: new Set(), providers: [\"opencode-go\"], rootRef: \"opencode-go/mid\" })\n const text = tableText(t, \"advanced\", \"opencode-go/mid\")\n assert.match(text, /MODEL OPTIONS — tier=advanced/)\n assert.match(text, /Baseline .*opencode-go\\/mid/)\n assert.match(text, /opencode-go\\/mid\\s+.*← your model \\(standard\\)/)\n assert.match(text, /set_tier_model/)\n assert.match(text, /not a recommendation and not a ranking/i)\n assert.match(text, /RELATIVE to the baseline/i)\n})\n\ntest(\"tableText separates measured candidates from score-less models and forbids picking them\", () => {\n const catalog = [\"opencode-go/cheap-small\", \"opencode-go/mid\", \"opencode-go/beast\", \"opencode-go/unmeasured\"]\n const t = modelTable({ report, fetchedAt: Date.now(), stale: false, catalog, dead: new Set(), providers: [\"opencode-go\"], rootRef: \"opencode-go/mid\" })\n const text = tableText(t, \"simple\", \"opencode-go/mid\")\n assert.match(text, /MEASURED \\(has a benchmark score\\)/)\n assert.match(text, /NO BENCHMARK/)\n assert.match(text, /do NOT propose one of these/i)\n assert.match(text, /Prefer a MEASURED row/i)\n assert.match(text, /Show this table to the user/i)\n assert.ok(\n text.indexOf(\"opencode-go/cheap-small\") < text.indexOf(\"opencode-go/unmeasured\"),\n \"measured rows are listed before score-less rows\",\n )\n})\n\ntest(\"alternativesDigest returns only measured models, cheapest first, excluding the chosen one\", () => {\n const catalog = [\"opencode-go/cheap-small\", \"opencode-go/mid\", \"opencode-go/beast\", \"opencode-go/unmeasured\"]\n const t = modelTable({ report, fetchedAt: Date.now(), stale: false, catalog, dead: new Set(), providers: [\"opencode-go\"] })\n const digest = alternativesDigest(t, \"opencode-go/cheap-small\", 6)\n assert.equal(digest.length, 2, \"only the two other measured models\")\n assert.ok(digest[0].startsWith(\"opencode-go/mid\"), \"cheapest measured alternative first\")\n assert.ok(digest[1].startsWith(\"opencode-go/beast\"))\n assert.ok(!digest.some((d) => d.includes(\"unmeasured\")), \"score-less model excluded\")\n})\n\ntest(\"modelSummary flags a score-less model as unmeasured\", () => {\n const catalog = [\"opencode-go/unmeasured\"]\n const t = modelTable({ report, fetchedAt: Date.now(), stale: false, catalog, dead: new Set(), providers: [\"opencode-go\"] })\n assert.match(modelSummary(t.rows[0]), /score —/)\n})\n~/.config/opencode/tests/context-sentinel.test.mjsimport { test } from \"node:test\"\nimport assert from \"node:assert/strict\"\nimport { mkdtempSync, readFileSync, readdirSync, existsSync } from \"node:fs\"\nimport { tmpdir } from \"node:os\"\nimport { join } from \"node:path\"\nimport { ContextSentinel } from \"../plugins/context-sentinel.ts\"\n\nconst fakeClient = (messages, todos = []) => ({\n app: { log: async () => {} },\n config: { providers: async () => ({}) },\n session: {\n messages: async () => messages,\n todo: async () => todos,\n },\n tui: { showToast: async () => {} },\n})\n\nconst user = (text) => ({ info: { role: \"user\" }, parts: [{ type: \"text\", text }] })\nconst summaryMsg = (text) => ({\n info: { role: \"assistant\", summary: true, mode: \"compaction\" },\n parts: [{ type: \"text\", text }],\n})\nconst writeTool = (filePath) => ({\n info: { role: \"assistant\" },\n parts: [{ type: \"tool\", tool: \"write\", state: { input: { filePath } } }],\n})\n\nconst checkpointFile = (dir) => {\n const cpDir = join(dir, \".opencode\")\n if (!existsSync(cpDir)) return null\n const name = readdirSync(cpDir).find((f) => f.startsWith(\"CHECKPOINT-\"))\n return name ? join(cpDir, name) : null\n}\n\ntest(\"compacting hook writes a verbatim, model-independent checkpoint and forbids tools\", async () => {\n const dir = mkdtempSync(join(tmpdir(), \"sentinel-\"))\n const messages = [\n user(\"FIRST user instruction verbatim\"),\n writeTool(\"src/app.ts\"),\n user(\"SECOND instruction — important, do not paraphrase\"),\n ]\n const plugin = await ContextSentinel({\n client: fakeClient(messages, [{ status: \"in_progress\", content: \"finish hook\" }]),\n directory: dir,\n })\n const output = { context: [] }\n await plugin[\"experimental.session.compacting\"]({ sessionID: \"ses_test\" }, output)\n assert.match(output.prompt, /Do NOT call tools/)\n assert.match(output.prompt, /FIRST user instruction verbatim/)\n assert.match(output.prompt, /SECOND instruction/)\n const file = checkpointFile(dir)\n assert.ok(file, \"checkpoint file must be written\")\n const content = readFileSync(file, \"utf8\")\n assert.match(content, /autograph: created by context-sentinel/)\n assert.match(content, /SECOND instruction/)\n assert.match(content, /- src\\/app\\.ts/)\n assert.match(content, /finish hook/)\n const ac = { enabled: false }\n await plugin[\"experimental.compaction.autocontinue\"]({ sessionID: \"ses_test\" }, ac)\n assert.equal(ac.enabled, true, \"autocontinue allowed when a checkpoint exists\")\n})\n\ntest(\"a tool-call compaction digest is rejected; mechanical file stays authoritative\", async () => {\n const dir = mkdtempSync(join(tmpdir(), \"sentinel-\"))\n const messages = [\n user(\"save this verbatim\"),\n summaryMsg('node -e \"Object.keys(report.json)\"'),\n ]\n const plugin = await ContextSentinel({ client: fakeClient(messages), directory: dir })\n await plugin[\"experimental.session.compacting\"]({ sessionID: \"ses_a\" }, { context: [] })\n await plugin.event({ event: { type: \"session.compacted\", properties: { sessionID: \"ses_a\" } } })\n const content = readFileSync(checkpointFile(dir), \"utf8\")\n assert.doesNotMatch(content, /MODEL DIGEST/, \"tool-call must not be stored as a digest\")\n})\n\ntest(\"a long prose compaction digest is accepted and appended\", async () => {\n const dir = mkdtempSync(join(tmpdir(), \"sentinel-\"))\n const prose = \"## TASK\\n\".concat(\"Very long meaningful digest. \".repeat(20))\n const messages = [user(\"do the work\"), summaryMsg(prose)]\n const plugin = await ContextSentinel({ client: fakeClient(messages), directory: dir })\n await plugin[\"experimental.session.compacting\"]({ sessionID: \"ses_b\" }, { context: [] })\n await plugin.event({ event: { type: \"session.compacted\", properties: { sessionID: \"ses_b\" } } })\n const content = readFileSync(checkpointFile(dir), \"utf8\")\n assert.match(content, /MODEL DIGEST/)\n assert.match(content, /Very long meaningful digest/)\n})\n\ntest(\"no checkpoint -> autocontinue is disabled (session will not silently continue)\", async () => {\n const dir = mkdtempSync(join(tmpdir(), \"sentinel-\"))\n const plugin = await ContextSentinel({ client: fakeClient([]), directory: dir })\n await plugin[\"experimental.session.compacting\"]({ sessionID: \"ses_c\" }, { context: [] })\n assert.equal(checkpointFile(dir), null, \"empty session writes no file\")\n const ac = { enabled: true }\n await plugin[\"experimental.compaction.autocontinue\"]({ sessionID: \"ses_c\" }, ac)\n assert.equal(ac.enabled, false)\n})\n~/.config/opencode/skills/<name>/SKILL.md + command/<name>.md (lazy task flow)A task flow is a skill. Only name + description are always-on (the catalog); the body is\nloaded only when the skill is invoked. A project can carry its own copy under\n<project>/.opencode/skills/<name>/SKILL.md (tracked; see §4.7).
---\nname: <task-flow>\ndescription: Use when <trigger> — <what the flow does>. Trigger on <phrases/situations>.\n---\n\n# <Task flow>\n1. <contract / red / green / verify / commit — your flow's steps>\n2. <step>\nA thin command makes the flow discoverable without bloating the digest — it forces the skill\nto load. The human runs it as /<name>:
---\ndescription: <what invoking this runs>\n---\nCall the `skill` tool with the name `<task-flow>` and follow it end to end. Do NOT act, edit\nfiles, or touch git before the skill is loaded — it owns the whole path.\n\nWhat to work on (may be empty — then ask the human):\n\n$ARGUMENTS\nThis section installs the agent-control side of the project loop. The companion\nrequirements-machine dump installs §4.3, §4.5, §4.9, §4.15 and §4.16; the numbering\nfollows the combined guide, so the gaps below are exactly those sections.
\n<project>/.gitignore# personal/ephemeral artifacts of the context machine\n/STATE.md\n# ephemeral compaction checkpoints (context-sentinel); lazy layers under .opencode/ stay TRACKED\n.opencode/CHECKPOINT-*.md\ndocs/wip-*/\nPlus an inner .opencode/.gitignore that ignores only the ephemeral runtime files, so the\nlazy layers (skills/, command/) remain tracked:
node_modules\npackage.json\npackage-lock.json\nbun.lock\n.gitignore\n<project>/package.json (minimal skeleton){\n \"type\": \"module\",\n \"scripts\": {\n \"test\": \"<project test runner>\",\n \"req\": \"node scripts/req-coverage.js\",\n \"state:diet\": \"node scripts/state-diet.mjs\",\n \"workflow-arrows:lint\": \"node scripts/workflow-arrows-lint.mjs\",\n \"contract\": \"node scripts/contract.mjs\"\n }\n}\nnpm run contract builds AGENTS/code-map.md from the contract-headers of the source\nmodules and the UI files; it FAILS (exit 1) when a module has no header or violates the\nlayout rule, so the generated map cannot silently drift from the code. Edit the headers,\nnever the generated map.
<project>/scripts/state-diet.mjsSTATE.md diet: chronicle below the marker moves to docs/history/state.md, only \"now\" remains in the head.
#!/usr/bin/env node\n// scripts/state-diet.mjs — move the STATE.md chronicle (below the marker) into\n// docs/history/state.md (newest archive on top). UTF-8/EOL-safe (node ops only).\n\nimport { readFileSync, writeFileSync, existsSync, mkdirSync } from \"node:fs\"\nimport { join, dirname } from \"node:path\"\n\nconst ROOT = new URL(\"..\", import.meta.url).pathname\nconst MARKER = \"<!-- ARCHIVE:BELOW -->\"\n\nconst statePath = join(ROOT, \"STATE.md\")\nconst content = readFileSync(statePath, \"utf8\")\nconst lines = content.split(\"\\n\")\nconst idx = lines.findIndex((l) => l.trim() === MARKER)\n\nif (idx < 0) {\n console.error(`state:diet: no \"${MARKER}\" line in STATE.md — refusing (no silent rewrite).`)\n process.exit(1)\n}\n\nconst head = lines.slice(0, idx + 1).join(\"\\n\") // head INCLUDING the marker line\nconst chronicle = lines.slice(idx + 1).join(\"\\n\").trim()\n\nif (!chronicle) {\n console.log(\"state:diet: chronicle empty — nothing to move.\")\n process.exit(0)\n}\n\nconst histDir = join(ROOT, \"docs\", \"history\")\nmkdirSync(histDir, { recursive: true })\nconst histPath = join(histDir, \"state.md\")\nconst stamp = new Date().toISOString().slice(0, 10)\nconst prev = existsSync(histPath) ? readFileSync(histPath, \"utf8\") : \"\"\n\nwriteFileSync(histPath, `## Archive ${stamp}\\n${chronicle}\\n\\n${prev}`, \"utf8\")\nwriteFileSync(statePath, head + \"\\n\", \"utf8\")\nconsole.log(`state:diet: moved ${chronicle.length} chars -> ${histPath}`)\n<project>/STATE.md (initial checkpoint)# STATE.md — checkpoint \"what we are doing now\" (NOT a product journal; untracked, in .gitignore)\n\nUpdated: <date>. Branch `main`. Suite green; `npm run req` 0.\n\n- Compaction checkpoint (ephemeral): `.opencode/CHECKPOINT-*.md` — will appear after the first compaction;\n on a new compaction context-sentinel will name the fresh path — write it here.\n\n## Now\n- Project just deployed: requirements management mechanism and agent-control installed, domain is empty.\n- Next step: <first task>.\n\n<!-- ARCHIVE:BELOW -->\n<project>/AGENTS.md (startup digest)# AGENTS.md — <project>\n\nInstructions for agents (and humans) working with this repository.\n\n## What is this\n<One paragraph: what the project does. Fill in.>\n\n## Language\nDon't rewrite existing text in the repo's current language — that's churn, not value. NEW\ncontent (code comments, doc additions, commit messages) goes in the language agreed for\nthe project. Human-facing UI strings keep their current language.\n\n## Terminology (accumulate, don't invent new)\nFull dictionary — **AGENTS/domain-model.md**: product runtime terms + our\ndeveloper terms. Accumulate new terms there; the section grows as we work.\n\n## Philosophy and values\n1. **TDD is mandatory.** Red → green: the contract is fixed by a test before implementation.\n Regressions are caught by the suite, not by hope. A commit without a green `npm test` is unacceptable.\n2. **Declarativity.** Extension point = a file (md/json/registry entry), not code, where possible.\n3. **Action only through explicit consent.** Irreversible actions — through gates and\n human confirmation; read-only autonomy — a separate requirement, not a default right.\n4. **Fail-visible.** Broken verdict, model/integration error, unknown format — visible\n error or alert, never silent swallowing.\n5. **One truth per entity.** Every fact lives in one place; during migrations, old sources are deleted.\n6. **Security always.** Escaping user/external input, secrets outside the repository,\n human labor is never deleted silently.\n7. **Mechanism, not a request.** A weak model does not execute prose prohibitions — the contract\n is held by the determinism of code and the grammar of schemas (gates, guards), not by phrasing in the prompt.\n8. **A bug is a symptom of a class.** A live case is formulated as a class of problems and fixed systemically at once;\n hardcoding a symptom (one if for a case) is not a fix. If \"model weakness\" — first prove\n that it's not a prompt that confused it.\n9. **Extend the flow, don't route around it.** A feature is built into the existing flow\n that owns its concern — never by a parallel path bypassing the common step. Before\n changing a part, read the flow map (`AGENTS/workflow-arrows.md`).\n\n## Requirements registry — AGENTS/requirements.md\n`REQUIREMENTS.md` is the single registry (stable `<PREFIX>-<GROUP>-NN` + tests;\n`docs/ideas/` — raw material and verdicts). **The file can grow large — do not read it entirely:**\nsearch with `Grep` by requirement strings, read the region with `Read`, coverage — `npm run req`\n**before every commit**. Maintenance protocol — **AGENTS/requirements.md**.\n\n## TDD cycle for a typical change\n1. **Contract.** Define a requirement/extend an existing one, add ID to the registry.\n2. **Red.** Test with ID in the title; run — it fails.\n3. **Green.** Implementation with minimal change; all contract consumers updated.\n4. **Suite + registry.** Entire suite and `npm run req`; fix the summary table if statuses changed.\n5. **Commit.** Message — one-line \"history\" (what — how/why — edge cases),\n requirement IDs in parentheses after the essence.\n\n## Structure\n\n### Lazy layers — keep the startup digest small\n`AGENTS.md` loads for every agent and every delegate, so only the digest is always-on; everything else is lazy:\n- **Area rules.** A nested `AGENTS.md` (e.g. `packages/<pkg>/AGENTS.md`) is auto-injected by opencode\n when an agent `read`s a file under that path (read-triggered only — `grep`/`glob`/`write` do NOT\n trigger it). Repo-wide rules stay in this file; package-scoped rules move to the package file.\n- **Task flows (skills).** `.opencode/skills/<name>/SKILL.md`: only `name` + `description` are\n cataloged always-on; the body enters context when the skill is invoked.\n- **Commands.** `.opencode/command/<name>.md`: a thin slash-command whose body says \"call the skill\n tool with name X\", which reliably forces the skill to load; `$ARGUMENTS` is substituted.\nRule: **what is read at startup must not grow** — only what is read on demand grows.\n\n### Maps — on demand (AGENTS/code-map.md)\nModule maps and \"Hot zones\" — in **AGENTS/code-map.md**: so as NOT to traverse files in order,\nbut to take the zone from the map and make ONE targeted read of the needed region (offset/limit).\n\n### Flow map — `docs/workflow-arrows.puml` (AGENTS/workflow-arrows.md)\nLinted map of code and numbered cross-cutting flow. Read it before changing a part to\nextend the existing flow, not to lay a parallel path bypassing it. How to\nread/maintain/lint/render — **AGENTS/workflow-arrows.md**; drift alarm —\n`npm run workflow-arrows:lint` (silent and exit 0 when the map matches the code).\n\n## Tools (dev) — AGENTS/tools.md\nFull rules, protocols, and \"iron\" caveats for each development tool —\n**AGENTS/tools.md**; here only the list with the essence.\n\n## STATE.md — checkpoint \"what we are doing now\" (NOT a product journal)\n- `STATE.md` in the root (untracked) is maintained by the agent: uncommitted changes, current batch,\n next step, flakes. **Read it first** in a new session and **update it at the end of each batch** —\n this is insurance against sudden compaction, NOT a release history (git remembers that). Keep the\n head tiny: if it grew — move the excess below the marker/to the archive.\n- **Diet**: the marker `<!-- ARCHIVE:BELOW -->` separates the head (current state) from the chronicle;\n after finishing a batch — `npm run state:diet` (chronicle moves to `docs/history/state.md`, new\n archives on top). The head contains only \"now\".\n- **Link with compaction**: context-sentinel puts a mechanical checkpoint during compaction\n `.opencode/CHECKPOINT-*.md` (verbatim last human replicas + todo + touched files)\n and appends the model digest to `STATE.md` BELOW the marker. The sentinel names the path of the fresh checkpoint\n in the toast and injects it into the context — write it into the head of `STATE.md` as a durable pointer.\n\n### Recovery protocol — after starting a session or compaction\n1. **STATE.md head only** (up to the `<!-- ARCHIVE:BELOW -->` marker; read with line limit).\n2. **Fresh compaction checkpoint**: if there was just a compaction — read\n `.opencode/CHECKPOINT-*.md` (sentinel names the file in the toast and injects its path):\n verbatim last human replicas, todo, touched files — do not reconstruct them by traversal.\n3. **Take the task zone from the map** — **AGENTS/code-map.md**: one targeted read of the needed region.\n4. **Overview traversals are forbidden**: mass reads of entire files and chains of\n grep→read→rereading after compaction — wasting tokens on reconstructing what\n the map already knows.\n\n## Context machine — how it works (AGENTS/context-machine.md)\nStart: system prompt = base + compact summary + **AGENTS.md** (digest with pointers);\n`AGENTS/*`, `REQUIREMENTS.md`, `STATE.md`, `docs/*` — on demand. Beyond the digest there are\n**lazy layers**: area rules (nested `AGENTS.md`, injected on read), task flows\n(`.opencode/skills/`, only the catalog is always-on) and commands (`.opencode/command/`).\n**Compaction** (context-sentinel): toast at 70/85% → checkpoint → `/compact`; mechanical\ncheckpoint is always written; digest is validated. **Delegation**: heavy step — to a\nsubagent with a fresh context, root holds the vision. Details and motivation —\n**AGENTS/context-machine.md** (read on demand, not at startup).\n\n## Cleanup (self-cleaning) — \"clean up after yourself\"\nFiles read at startup (AGENTS.md) and checkpoints must not grow. After finishing a batch:\n- `npm run state:diet` — head of `STATE.md` = only \"now\".\n- `AGENTS.md` — digest. Do not append chronicles and process notes to it: their place is in\n `STATE.md`/`docs/`, not in the startup prompt.\n- Compaction checkpoints `.opencode/CHECKPOINT-*.md` are ephemeral: after compaction only the\n fresh one is needed; delete the old ones.\n- Keep one-time dumps/probes only as needed for analysis; the rest — to `docs/history/` or out.\n- Rule: **what is read at startup — does not grow**; only what is read on demand grows.\n\n## Tool-call traps (proven in practice)\n- Send long command output to a file (`… > \"$env:TEMP\\out.txt\"` / `> /tmp/out.txt`),\n then parse with a script; inline scripts with complex quotes/unicode break —\n write temporary script files.\n- Do not do string replacements in files via shell means (like PowerShell `-replace`) —\n they silently corrupt cyrillic/EOL; use node scripts or Edit tools.\n- A full suite run can take a minute; restart known flakes separately before fixing.\n- Git: only `git add <specific files>`; there are human untracked files in the tree —\n `git add -A` pulls them into the commit.\n\n## Commands\n```bash\nnpm test # entire suite\nnpm run req # reconcile test IDs with requirements registry\nnpm run contract # rebuild AGENTS/code-map.md from contract-headers (drift → exit 1)\nnpm run state:diet # chronicle STATE.md → docs/history/state.md\nnpm run workflow-arrows:lint # flow map drift alarm (silent when map is clean)\nDelegation mode — for the root session only; subagents (worker, worker-lite,\nexplore) ignore it. Enabled by a human phrase (\"let's work in delegation mode\"...);\nwhen enabled, read AGENTS/delegation-mode.md and follow the protocol (roles, cycle,\nmodel selection, brief template, context discipline). Canonical master —\n~/.config/opencode/templates/delegation-mode.md.
\n### 4.8 `<project>/AGENTS/README.md` (add-ons pointer)\n\n```markdown\n# AGENTS/ — add-ons to AGENTS.md (startup digest)\n\n`AGENTS.md` is loaded into the system prompt of **every** agent and delegate. Everything needed\nnot every turn, but on demand, is moved here: **read only the needed file and only its\nregion** (offset/limit).\n\nThree other lazy layers live OUTSIDE this folder, so the always-on digest stays small:\n- **Area rules** — a nested `AGENTS.md` (e.g. `packages/<pkg>/AGENTS.md`), auto-injected by\n opencode when a file under that path is `read`.\n- **Task flows** — `.opencode/skills/<name>/SKILL.md`; only the catalog (name + description) is always-on.\n- **Commands** — `.opencode/command/<name>.md`, a thin trigger that loads a skill (`$ARGUMENTS`).\n\n| file | what's inside | when to read |\n|------|-----------|--------------|\n| [code-map.md](code-map.md) | code map: where is what, \"Hot zones\" | need an overview \"where is what\": task zone, target file |\n| [workflow-arrows.md](workflow-arrows.md) | flow map: how to read/maintain/lint/render `docs/workflow-arrows.puml` | need a picture of the cross-cutting flow or flow map lint is red |\n| [delegation-mode.md](delegation-mode.md) | delegation protocol — **root-only** | delegation mode is enabled |\n| [tools.md](tools.md) | full rules for dev tools | before using a tool |\n| [requirements.md](requirements.md) | requirements registry protocol | working with `REQUIREMENTS.md` |\n| [context-machine.md](context-machine.md) | why the context machine is structured this way | need to understand the motivation |\n| [domain-model.md](domain-model.md) | unified terminology dictionary | need terminology |\n\n## Why these files, and not \"just read the code\"\n- **Map instead of traversal.** Prefer the map to file traversal; overview reads of entire\n files are a waste of context.\n- **STATE is a checkpoint, not a history.** Keep the head tiny and current; history moves\n to `docs/history/state.md`.\n- **Generation doesn't lie.** Everything generated is compared with the code; don't edit manually generated stuff.\n<project>/AGENTS/delegation-mode.mdCopy of the ## DELEGATION MODE section from ~/.config/opencode/templates/delegation-mode.md (§3.11) with a header:
# DELEGATION MODE — delegation protocol (root-only)\n\n> Master copy: `~/.config/opencode/templates/delegation-mode.md`. Moved out of AGENTS.md\n> so as not to load at startup for subagents (they must ignore it). Root reads this\n> file when delegation mode is enabled.\n\n<verbatim the \"## DELEGATION MODE — delegation workflow for heavy tasks\" section from the master copy>\n<project>/AGENTS/context-machine.md# context-machine — how the context machine works\n\n> Read if you need to understand **why** the context is structured exactly this way: compaction, delegation,\n> `STATE.md` diet, startup cost. The logic canon is the plugins `~/.config/opencode/plugins/`\n> (and `templates/delegation-mode.md`); this file is their compact model and motivation, not a copy.\n\n## 1. Budget and startup layers\n- The real model limit can be large, but `opencode.jsonc` holds the **effective cap**\n (e.g. 250k): quality/latency/price degrade around 200–250k.\n `compaction { auto, reserved, preserve_recent_tokens }` pulls the last ~30k tokens\n of the dialogue through compaction **verbatim** (the task tail).\n- Agent/delegate start = base system prompt + compact summary + **`AGENTS.md`** (digest).\n This is expensive — therefore `AGENTS.md` is a digest, not a dump.\n- **Lazy layers beyond the digest.** Area rules live in a nested `AGENTS.md` (e.g.\n `packages/<pkg>/AGENTS.md`): opencode injects them as a system-reminder when a file under\n that path is `read` (once per message; `grep`/`glob`/`write` do not trigger). Task flows\n live in `.opencode/skills/<name>/SKILL.md`: always-on is only the catalog (name +\n description), the body loads on skill invocation. Commands (`.opencode/command/<name>.md`)\n are thin triggers that force a skill load. All three keep the always-on digest small.\n- Read on demand: `AGENTS/*`, `REQUIREMENTS.md`, `STATE.md`, `docs/*`.\n Hence the rule: **what is loaded at startup — does not grow**.\n\n## 2. Compaction (context-sentinel) — mechanism, not hope in the model\nPrinciple: **do not depend on the summarizer model and do not stay silent**.\n1. **Warning.** Toasts at 70% (yellow) / 85% (red) of the effective limit: time to\n write a checkpoint and do `/compact`. Child (subagent) sessions do not wake the root.\n2. **Mechanical checkpoint.** `<project>/.opencode/CHECKPOINT-<stamp>.md` — verbatim\n last human replicas + todo + files from tool-calls. Written **always**, even if\n the model outputs nothing. The path is pushed into the context and into the toast after compaction.\n3. **Prompt replacement.** Structural checkpoint-prompt, **forbids tool-calls**;\n verbatim block is duplicated directly into the prompt so the digest doesn't lose the human's words.\n4. **Digest validation.** Digest is accepted only if it is prose (no tool-call syntax,\n not shorter than minimum); otherwise the mechanical file remains the main one, `warn` to log.\n `autocontinue` — only if the checkpoint file exists.\n5. **Why this way.** Live failure: the summarizer model returned a **tool-call instead of a digest**,\n compaction passed \"silently\". Hence — mechanical fallback, validation, and explicit logs\n (principle **fail-visible**).\n\n## 3. STATE.md — checkpoint \"now\", not product history\n- Head (up to the `<!-- ARCHIVE:BELOW -->` marker) = what we are doing **right now**; finished\n moves to `docs/history/state.md` (`npm run state:diet`). Compaction digest — below the marker.\n- Checkpoint files `.opencode/CHECKPOINT-*.md` are ephemeral; in the head of `STATE.md` we keep a pointer to the fresh one.\n\n## 4. Delegation (delegate plugin + `AGENTS/delegation-mode.md`)\n- **Why.** A heavy step bloats the root → compaction → amnesia → repeated recon.\n Solution: the step is executed by a **subagent with a fresh context**, the root receives only\n a short report and holds the vision.\n- One subagent at a time. Brief is self-sufficient — the child **does not see** the history.\n- **Models are not hardcoded** in agent files/tiers: chosen on call via `delegate_*` +\n `set_tier_model` (with human approval). Live lesson: hardcoding a model breaks silently\n when the model becomes `Forbidden`.\n- **Cost.** The child always has a fresh context (cache miss) → every delegation costs tokens;\n therefore tiers are `ask` by default.\n\n## 5. Code maps (`AGENTS/code-map.md`)\nThe agent by habit goes `grep`→`read` through all files in a row. The map (built by\n`npm run contract` from the contract-headers of source modules and the UI files) answers\n\"where is what\" without traversal and **cannot lie** — drift fails the build (exit 1).\nPrefer one targeted `read` of the needed region from the map; edit the headers, not the map.\n\n## 6. Machine principles\n- **Fail-visible** — error = visible alert or log, never silence.\n- **Mechanism, not a request** — contracts are held by gates and grammar, not by persuasion.\n- **Move-verbatim** — protocols are transferred verbatim + pointer, not rewritten by meaning.\n- **One truth per entity.**\n- **Lazy by default** — what is loaded at startup does not grow; area rules, skills and\n commands load on demand.\n- **Self-cleaning** — startup prompt does not grow; STATE diets; checkpoints are ephemeral.\n<project>/AGENTS/tools.md (skeleton for project tools)# tools — dev tools of <project>\n\n> Full rules and protocols of the tools with which the agent runs the server, catches bugs, and\n> analyzes incidents. In `AGENTS.md` — only the list with the essence and a link here.\n> Read on demand before using a tool.\n\n## Server process — iron rules\n- Never start the server in the foreground from a tool: the child process inherits console handles\n and the tool-call hangs forever. Start/stop — scripts with handle redirection.\n- Each tool call — separate and short (timeout ≤30 s); do not chain\n \"commit + restart + check\" in one call.\n- Server code requires a restart; data/templates read from disk — live.\n\n## Semi-real runs\n<Emulator of user UI over a live API: every step via an external watchdog,\nall fetches with deadlines; a found bug is released as a deterministic test with an ID.>\n\n## Analysis of live incidents\n<Extracting the course from the log into a readable batch of files; protocol: by which fragment to search,\nhow to name folders.>\n<project>/AGENTS/code-map.md (skeleton)# code-map — code map: where is what and how to read it\n\nAnti-traversal: DO NOT read files in a row. Take a zone from here and make ONE targeted read of the needed\nregion (offset/limit).\n\n### Flow diagram — `docs/workflow-arrows.puml` (+ generated `.svg`)\nOne-screen map of how a request goes through the code: each `src/` folder and numbered path\nof the cross-cutting flow (`1..N`). Read before changing the flow to extend it in place, not to\nlay a parallel path bypassing it. Lint — `npm run workflow-arrows:lint`. How to\nread/maintain/render → **AGENTS/workflow-arrows.md**.\n\n### src — module map\n<!-- Filled by the map generator from module headers (contract-headers in sources)\n or manually at project start. Generation cannot lie: discrepancy with code fails\n the check. While there are no maps — keep only \"Hot zones\" here. -->\n\n### Hot zones (hand-maintained — verify with code before use)\n- <zone>: `<file>:<function>` — what lives there and the extension point.\n\n### Workspace tree\n<brief directory tree with roles>\n<project>/AGENTS/domain-model.md (dictionary skeleton)# domain-model — terminology dictionary of <project>\n\n> Unified project dictionary, two clearly separated layers. The section grows as we work;\n> accumulate new terms here, do not invent them anew.\n\n## Part A. Product runtime terms\n<Terms seen by the agent/product user: canon + translations. If you edit terminology\nin prompts/schemas — synchronize this dictionary in the same commit.>\n\n## Part B. Our developer terms\n<Working language of those who write code: short definitions. There are no such terms\nin the product agent's system message.>\n\n## Sources and where the truth is (do not duplicate)\n- Runtime terms — live system prompt/schemas (aggregate here).\n- Developer terms — this file.\n<project>/docs/history/state.md# STATE archive\n<empty at start — `npm run state:diet` puts archives here (newest on top)>\n<project>/scripts/workflow-arrows-lint.mjsFlow map linter: compares docs/workflow-arrows.puml with the code tree. lintDiagram() is pure over text (reads the file system only to resolve links and list folders); CLI is silent and exit 0 when the map is clean, and prints a pointer to AGENTS/workflow-arrows.md + DRIFT ... lines on drift. Project-specific roots are set by constants SRC_TREE/PACKS_TREE; on an empty project both folders are absent — empty map against empty coverage = clean lint.
#!/usr/bin/env node\n// workflow-arrows-lint — linter for docs/workflow-arrows.puml.\n//\n// The diagram is a hand-drawn map of the code tree: folder blocks (`package\n// \"src/<dir>\"`), module bricks (`component ... <<theme>> [[file#symbol]]`), pack\n// blocks (`package \"npm: <pkg>\"`) and a numbered flow (labels `N · call` /\n// `N ⟵ return`). Everything in it points at real things; nothing in it is\n// checked by the compiler. This linter is the drift alarm:\n//\n// (A) folder coverage both ways — declared src/<dir> vs src/ on disk\n// (B) pack coverage both ways — declared npm:<pkg> vs folders of packages/\n// (C) every [[url]] resolves to an existing file (relative to docs/)\n// (D) a link's #symbol is declared in the target file\n// (E) the flow's step numbers are exactly 1..N, unique and contiguous\n// (F) a brick's stereotype equals its enclosing src/<dir> folder\n// (G) T3 idiom — a numbered call to a module brick carries a [[file#symbol]]\n// link; a numbered return carries none\n//\n// lintDiagram() is pure over `text`; it reads the filesystem only to resolve\n// links and list folders. An empty array means clean. The CLI exits 1 on any\n// problem and stays silent when the diagram is clean.\n//\n// Project-specific: the two source trees below. On a fresh project both may be\n// absent — empty coverage against an empty diagram is a clean lint.\n\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { fileURLToPath, pathToFileURL } from 'node:url';\n\nconst ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');\nconst SRC_TREE = 'src'; // module folders: `package \"src/<dir>\"`\nconst PACKS_TREE = 'packages'; // optional packs: `package \"npm: <pkg>\"`\nconst DEFAULT_PUML = path.join(ROOT, 'docs', 'workflow-arrows.puml');\n\n// A link carries a scheme when it is not a repo-relative file reference.\nconst SCHEME = /^(?:www\\.|https?:|mailto:|about:)/i;\n\n// Stereotypes that are not \"<src folder>\" themes: externals and pack bricks.\nconst EXEMPT_STEREOTYPES = new Set(['ext', 'pack', 'p_pack']);\n\n// The guidance a red lint prints BEFORE the DRIFT lines. A failing check must\n// send the reader to the rules (fix the diagram / the code), never to a weakened\n// check. Exported so a project test can pin the pointer.\nexport const DRIFT_GUIDANCE = [\n 'workflow-arrows-lint: docs/workflow-arrows.puml has drifted from the code.',\n 'Maintenance rules + how to read it: AGENTS/workflow-arrows.md',\n 'then make the diagram match the code — or fix the code if the change was',\n 'unintended. Never weaken/skip this check or erase bricks; re-render the .svg.',\n].join('\\n');\n\n// immediateDirs(dir) → sorted names of the direct subdirectories ([] if absent)\nfunction immediateDirs(dir) {\n if (!fs.existsSync(dir)) return [];\n return fs\n .readdirSync(dir, { withFileTypes: true })\n .filter((e) => e.isDirectory())\n .map((e) => e.name)\n .sort();\n}\n\n// declaredFolders(text) → [\"agent\", \"http\", ...] from `package \"src/<dir>...\"`\nexport function declaredFolders(text) {\n return [...new Set([...text.matchAll(/^\\s*package\\s+\"src\\/([^\\\\\"]+)/gm)].map((m) => m[1].trim()))].sort();\n}\n\n// declaredPacks(text) → [\"pkg-a\", ...] from `package \"npm: <pkg>...\"`\nexport function declaredPacks(text) {\n return [...new Set([...text.matchAll(/^\\s*package\\s+\"npm:\\s*([^\\\\\"\\s]+)/gm)].map((m) => m[1].trim()))].sort();\n}\n\n// parseLinks(text) → [{ raw, url, file, symbol }]. The puml wraps a link as\n// [[<url>[ <label>]]]; the URL ends at the first space (the label may hold the\n// step number). `file` drops the fragment; `symbol` is the fragment (or null).\nexport function parseLinks(text) {\n const out = [];\n for (const m of text.matchAll(/\\[\\[([^\\]]+)\\]\\]/g)) {\n const raw = m[1];\n const sp = raw.indexOf(' ');\n const url = sp === -1 ? raw : raw.slice(0, sp);\n const hash = url.indexOf('#');\n out.push({\n raw,\n url,\n file: hash === -1 ? url : url.slice(0, hash),\n symbol: hash === -1 ? null : url.slice(hash + 1),\n });\n }\n return out;\n}\n\n// packageFrames(text) → the module bricks with their enclosing package:\n// [{ alias, st, pkg }]. A simple brace-depth scan keeps the innermost open\n// `package \"...\"` frame; `skinparam package { ... }` carries no quoted name\n// and is skipped.\nexport function packageFrames(text) {\n const out = [];\n const stack = [];\n let depth = 0;\n for (const line of text.split(/\\r?\\n/)) {\n const comp = line.match(/component\\s+\"[^\"]*\"\\s+as\\s+(\\w+)\\s*<<(\\w+)>>/);\n if (comp && stack.length) out.push({ alias: comp[1], st: comp[2], pkg: stack[stack.length - 1] });\n const pkg = line.match(/^\\s*package\\s+\"([^\"]*)\"/);\n const opens = (line.match(/\\{/g) || []).length;\n const closes = (line.match(/\\}/g) || []).length;\n if (pkg) stack.push({ name: pkg[1], depth });\n depth += opens - closes;\n while (stack.length && depth <= stack[stack.length - 1].depth) stack.pop();\n }\n return out;\n}\n\n// symbolDeclared(src, symbol) → true when the symbol is a declaration or a call\n// site (a reference alone is not enough: `#handleChat` must be a real member,\n// not a mention in a comment). This is what catches a renamed method.\nexport function symbolDeclared(src, symbol) {\n const s = symbol.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n return new RegExp(`\\\\b${s}\\\\s*\\\\(|(?:function|class|const|let|var)\\\\s+${s}\\\\b`).test(src);\n}\n\n// srcDirOf(pkgName) → \"http\" for `src/http\\n====...`, else null\nfunction srcDirOf(pkgName) {\n const m = pkgName.match(/^src\\/([^\\\\]+)/);\n return m ? m[1] : null;\n}\n\n// lintDiagram({ text, pumlDir, repoRoot }) → problems[] (empty = clean)\nexport function lintDiagram({ text, pumlDir, repoRoot }) {\n const problems = [];\n // (A) folders: the module tree, both directions\n const declaredDirs = declaredFolders(text);\n const diskDirs = immediateDirs(path.join(repoRoot, SRC_TREE));\n for (const d of declaredDirs) if (!diskDirs.includes(d)) problems.push(`phantom folder src/${d} (not on disk)`);\n for (const d of diskDirs) if (!declaredDirs.includes(d)) problems.push(`folder src/${d} not drawn`);\n // (B) packs: the packs tree, both directions\n const declaredPkg = declaredPacks(text);\n const diskPkg = immediateDirs(path.join(repoRoot, PACKS_TREE));\n for (const p of declaredPkg) if (!diskPkg.includes(p)) problems.push(`phantom pack ${p} (not on disk)`);\n for (const p of diskPkg) if (!declaredPkg.includes(p)) problems.push(`pack ${p} not drawn`);\n // (C) + (D) links resolve, and their #symbol is declared in the target\n for (const link of parseLinks(text)) {\n if (SCHEME.test(link.url)) continue;\n const target = path.resolve(pumlDir, link.file);\n if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {\n problems.push(`link target not found: ${link.file}`);\n continue;\n }\n if (link.symbol && !symbolDeclared(fs.readFileSync(target, 'utf8'), link.symbol)) {\n problems.push(`link symbol \"${link.symbol}\" not declared in ${link.file}`);\n }\n }\n // (E) step numbers: the labels must carry exactly 1..N, unique\n const nums = [...text.matchAll(/(\\d+)\\s*(?:·|⟵)/g)].map((m) => Number(m[1]));\n const seen = new Set();\n const dupes = new Set();\n for (const n of nums) {\n if (seen.has(n)) dupes.add(n);\n seen.add(n);\n }\n if (dupes.size) problems.push(`step numbering has duplicates: ${[...dupes].sort((a, b) => a - b).join(', ')}`);\n const max = seen.size ? Math.max(...seen) : 0;\n const missing = [];\n for (let i = 1; i <= max; i++) if (!seen.has(i)) missing.push(i);\n if (missing.length) problems.push(`step numbering has gaps: missing ${missing.join(', ')}`);\n // (F) a brick's stereotype must equal its enclosing src/<dir> folder\n for (const { alias, st, pkg } of packageFrames(text)) {\n if (EXEMPT_STEREOTYPES.has(st)) continue;\n const dir = srcDirOf(pkg.name);\n if (dir && st !== dir) problems.push(`stereotype <<${st}>> on brick \"${alias}\" mismatches enclosing folder src/${dir}`);\n }\n // (G) T3 idiom: a numbered call to a module brick must carry a\n // [[file#symbol]] link; a numbered return must carry none. Module bricks are\n // the packageFrames whose stereotype is not an exempt external/pack one.\n const modules = new Set(\n packageFrames(text)\n .filter((f) => !EXEMPT_STEREOTYPES.has(f.st))\n .map((f) => f.alias),\n );\n const ARROW = /^(\\w+)\\s+(?:-\\[[^\\]]+\\]->|-->|\\.\\.>)\\s+(\\w+)\\s*:\\s*(.*)$/;\n for (const line of text.split(/\\r?\\n/)) {\n const m = line.match(ARROW);\n if (!m) continue;\n const target = m[2];\n const label = m[3];\n const hasLink = label.includes('[[');\n if (/(\\d+)\\s*·/.test(label) && modules.has(target) && !hasLink) {\n problems.push(`numbered call to module \"${target}\" lacks a [[file#symbol]] link (T3)`);\n }\n if (/\\d+\\s*⟵/.test(label) && hasLink) {\n problems.push(`numbered return to \"${target}\" must not carry a link (T3)`);\n }\n }\n return [...new Set(problems)];\n}\n\n// CLI: read the diagram, print problems, exit 1 on any. Silent when clean.\nexport function main({ puml = DEFAULT_PUML, pumlDir = path.dirname(puml), repoRoot = ROOT } = {}) {\n let text;\n try {\n text = fs.readFileSync(puml, 'utf8');\n } catch (e) {\n console.error(`workflow-arrows-lint: cannot read ${puml}: ${e.message}`);\n process.exit(1);\n return;\n }\n const problems = lintDiagram({ text, pumlDir, repoRoot });\n if (problems.length) {\n console.error(DRIFT_GUIDANCE);\n console.error(problems.map((p) => `DRIFT ${p}`).join('\\n'));\n process.exit(1);\n }\n}\n\nconst isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;\nif (isMain) main();\n<project>/AGENTS/workflow-arrows.md# workflow-arrows — the workflow map (`docs/workflow-arrows.puml` → `.svg`)\n\nTwo files, one artifact:\n`docs/workflow-arrows.puml` — the machine source: plain text, the thing you\nedit, checked by the linter.\n`docs/workflow-arrows.svg` — the human render: generated from the `.puml`,\nthe thing people look at. Never edit it by hand. A fresh project has no `.svg`\nuntil the map has content and is rendered once.\n\nThe map starts empty and grows with the code: add a folder block when a `src/<dir>`\nappears, a brick when a module appears, a numbered arrow when a cross-cutting flow\nappears. The linter (`scripts/workflow-arrows-lint.mjs`) keeps it from rotting.\n\n## Why a trustworthy map\nCode maps usually rot: they show whatever modules someone happened to open last.\nThis one is linted against the code tree, so it either matches the code or the lint\ngoes red. That matters when you touch a cross-cutting flow: you can see the whole\npicture at once and extend the flow that already exists instead of adding a parallel\npath around it. A map you can trust is what prevents those workarounds.\n\nThink of the code as a park with a few main paths — the cross-cutting flows. A new\nfeature should widen a path or add a bench, not cut a flowerbed straight across one\nbecause that is the shortest line to the goal: the flowerbed \"works\" until someone\nwalks the path, and then it is just broken ground. A shortcut around a shared step\nis the same — it routes delivery around the step that owns the concern; locally\ngreen, globally a second truth that drifts. Widening the path is the work; cutting\nacross it is the bug.\n\n## How to read it\nBricks = modules, grouped in folders (`src/<dir>` blocks) and packs\n(`npm: <pkg>` blocks); a folder's header says why it exists.\nA brick reads `file.js` / `headlineMethod` / `role`.\nNumbered arrows = the flow order `1..N`. Label line 1 is\n`N · callee.method()` — the API method of the target brick (the callee).\nLabel line 2 (plain text) is why the call happens.\nSolid `-->` = a call; dashed `..>` = a return; dashed to the UI = an\nSSE push.\nClick targets: a brick opens its file, a call label opens the callee method\n(in the `.svg` + the IntelliJ PlantUML plugin).\n\n## Linted idioms (T1–T6)\nThe linter pins these; every new brick or arrow must obey them.\nT1 — a brick's stereotype equals its enclosing `src/<dir>` folder\n(exempt: `<<ext>>`, `<<pack>>`, `<<p_pack>>`).\nT2 — a folder's title first line is exactly `src/<dir>`.\nT3 — numbered call arrows carry a `[[file#symbol]]` link; returns carry no link.\nT4 — the step number is the label's first token: `N ·` for a call,\n`N ⟵` for a return.\nT5 — a brick's link may carry `#headlineSymbol`, and it must resolve.\nT6 — returns use `..>` and `⟵`.\n\n## The linter\n`scripts/workflow-arrows-lint.mjs`, pure `lintDiagram({ text, pumlDir, repoRoot })`.\nRun it from the project root (silent, exit 0 when clean):\n```bash\nnpm run workflow-arrows:lint\nChecks:\n(A) folder coverage both ways — declared src/<dir> ↔ subdirectories of src/.\n(B) pack coverage both ways — declared npm: <pkg> ↔ subdirectories of packages/.\n(C) every [[url]] resolves relative to docs/.\n(D) a link's #symbol is declared in the target file.\n(E) step numbers are exactly 1..N, unique and contiguous.\n(F) a brick's stereotype equals its enclosing src/<dir> (T1).\n(G) a numbered call to a module brick carries a [[file#symbol]] link;\na numbered return carries none (T3).
A red lint is the drift alarm, not an obstacle. Do this:
\nDRIFT lines — they name what drifted..svg after editing.The linter prints this file's path in the guidance for exactly this reason.
\nRender (Smetana layout — no GraphViz needed):
\njava -jar <plantuml.jar> -tsvg -charset UTF-8 docs/workflow-arrows.puml\nThen confirm the .svg holds no Syntax Error.
Links are relative to docs/:\n[[../src/<path>.js#symbol <label>]]. The label follows the URL after a\nspace — not {}. No absolute paths, no file:// (the IntelliJ plugin opens\nneither).
==== draws a divider inside a package title; -- draws one inside a\ncomponent body.
Commit .puml and .svg together — source and render are one artifact.
\n### 4.20 `<project>/docs/workflow-arrows.puml`\n\nMachine-readable flow map. Empty at start (no bricks, no flow) — filled as code appears; the linter keeps it in sync with the tree. In the empty state, lint is green (`src/` and `packages/` are absent → empty coverage).\n\n```plantuml\n@startuml\n' workflow-arrows — the linted map of the code tree and the cross-cutting flow.\n' How to read / maintain / lint / render: AGENTS/workflow-arrows.md.\n' This file starts EMPTY: no bricks, no flow. Add a folder block when a src/<dir>\n' appears, a brick when a module appears, a numbered arrow when a cross-cutting flow\n' appears. scripts/workflow-arrows-lint.mjs keeps the map from rotting; never edit the .svg.\n\n!pragma layout smetana\nskinparam backgroundColor #FFFFFF\nskinparam shadowing false\nskinparam componentStyle rectangle\nskinparam packageStyle rectangle\nskinparam linetype ortho\nskinparam ArrowFontSize 12\nskinparam ArrowFontColor #263238\nskinparam DefaultFontSize 12\nskinparam nodesep 18\nskinparam ranksep 28\n\n' Add one component theme per src/<dir>; <<ext>> is reserved for external actors/systems,\n' <<pack>>/<<p_pack>> for optional packs.\nskinparam component {\n BackgroundColor<<ext>> #FAFAFA\n BorderColor<<ext>> #9E9E9E\n BackgroundColor<<pack>> #F3E5F5\n BorderColor<<pack>> #8E24AA\n}\nskinparam package {\n BackgroundColor<<p_pack>> #F3E5F5\n BorderColor<<p_pack>> #8E24AA\n}\n\nleft to right direction\ntitle <project> — folders, bricks and the numbered flow (number · callee method · why)\n\n' ── bricks ─────────────────────────────────────────────────────────────────────\n' A brick is a component whose stereotype is its src/<dir> and whose lines read\n' file.js / headlineMethod / -- / role, linked to its file and its method.\n' A folder is a package titled \"src/<dir>\" + a divider + why it exists, wrapping bricks.\n' A pack is a package titled \"npm: <pkg>\" + a divider + role, stereotyped p_pack.\n' Keep this section empty while src/ is empty: the linter fails on a phantom folder.\n\n' ── flow ───────────────────────────────────────────────────────────────────────\n' Numbered arrows only, 1..N contiguous and unique; the number is the label's first token:\n' a call links the callee method of the TARGET brick and says why it happens;\n' a return carries no link and reads \"N ⟵ what comes back\".\n' solid = call · dashed = return · dashed to UI = SSE push.\n\nlegend right\n **how to read an arrow**\n line 1 (colored link): N · callee.method() — the API method\n of the TARGET brick this arrow calls (the callee)\n line 2 (plain text): why the call happens (business intent)\n solid = call · dashed = return · dashed to UI = SSE push\n click a brick → its file · click a call → the method's source\n\n **linted idioms** (workflow-arrows-lint): a brick's stereotype = its\n src/ folder; every numbered call links the callee method,\n returns carry no link; step numbers are exactly 1..N\nendlegend\n\n@enduml\n~/.config/opencode/ → npm install → npm test (both suites green).context-sentinel v1.5.0 loaded (warn=0.7, crit=0.85, …) and loading of delegate.list_models — should return a live list of the provider from routing.json.recommend_model({ tier: \"simple\" }) — either the feed table or an honest fallback \"feed unavailable → use list_models\" (both variants are correct).delegate_* (experimental.primary_tools)./compact — <project>/.opencode/CHECKPOINT-*.md with the sentinel's signature should appear; the toast will name the path.delegate_simple_task returns MODEL SELECTION REQUIRED (children do not start without model approval).name + description; invoking the matching command/<name>.md loads the skill body. A nested packages/<pkg>/AGENTS.md should appear as a system-reminder when a file under that path is read (and NOT when merely grep-ped).— cost · model … · child … · parent session spent … · delegated total this session … line (child spend does not roll into session.cost).npm run state:diet (visible refusal without marker — as intended; with marker — moving empty chronicle = \"nothing to move\"), npm run contract (rebuilds the code map; fails loudly on a missing header).npm run workflow-arrows:lint — exit 0 on empty diagram (lint is silent only when the map matches the code; drift → DRIFT ... lines and pointer to AGENTS/workflow-arrows.md).npm run req (exit 0 on the empty registry without tests).explore: read-only recon. worker: coherent implementation step. worker-lite: routine. One subagent at a time; brief is self-sufficient (TASK/CONTEXT/CONTRACT/SELF-CHECK/REPORT ≤60 lines).standard inherits the root model (no pin needed). For simple/advanced: table → propose one model to the human → set_tier_model (native approval, 24h pin per session) → repeat the same delegation call. A failed model is blacklisted for the session, fallback — root inheritance.STATE.md/checkpoint, then /compact while quality is high. On 85% — checkpoint immediately, auto-compact is close. After compaction: read the mechanical checkpoint BEFORE acting; model digest — only if it passed validation.npm run state:diet; AGENTS.md does not grow; delete old CHECKPOINT-*; one-time dumps — to docs/history/ or out.AGENTS.md; package-scoped rules in a nested AGENTS.md (loaded on read); long task flows as .opencode/skills/<name>/SKILL.md (only the catalog is always-on), triggered by .opencode/command/<name>.md. What is read at startup must not grow.mv plugins/context-sentinel.ts{,.disabled} + restart (or OPENCODE_CHECKPOINT_OFF=1). Delegate: mv plugins/delegate.ts{,.disabled} + remove from plugin[] + remove primary_tools / permission. All at once: OPENCODE_PURE=1 (OpenCode skips external plugins).AGENTS/code-map.md (map and hot zones), docs/workflow-arrows.puml (flow map + rendered .svg), AGENTS/domain-model.md (dictionary), runbook §5 (table of verified models).The requirements half — REQUIREMENTS.md, scripts/req-coverage.js,\nAGENTS/requirements.md and the docs/ideas/ process — is the second dump,\nThe requirements machine. Applied together with this one, the two reproduce the\ncombined context-machine-setup guide in full.
What it is. A complete, reproduction-ready OpenCode setup for running long\ncoding-agent sessions without losing the thread: a compaction \"sentinel\" plugin that\nalways writes a mechanical checkpoint, a tiered delegation plugin that lets the root\npush heavy steps to fresh-context subagents, an advisor for choosing models with human\napproval, and lazy layers that keep the always-on prompt small. Every config file,\nplugin and test is inlined.
\nWhy you would want it. Long sessions fail in two expensive ways. First, when the\ncontext window fills, the automatic summary can come back as garbage — so the machine\nwrites its own checkpoint (verbatim user posts, todo, touched files) that does not\ndepend on the summarizer at all. Second, digging through files bloats the root session\nuntil it forgets the plan — so heavy steps go to subagents with a fresh context, and\neverything not needed every turn (area rules, skills, commands) loads on demand. The\nresult: sessions survive compaction, models are chosen per task with approval instead of\nbeing hardcoded, and the startup prompt stays small.
\nWhat to watch out for. This is a field setup, not a product: it leans on OpenCode's\nexperimental.* plugin hooks, so a future release can move the ground under it. It is\nself-tested on one account and a couple of projects, not community-tested. The files\ncome with empty domain data and <...> placeholders — you fill in your provider and\nmodels. It is one of two companion dumps; the requirements registry, its coverage check\nand the idea process live in The requirements machine. Honesty labels:\ngenerated_by: agent, human_review: minimal, trust_level: self-tested. Personal\ndata (local username, absolute paths, internal project names) was removed — see\nREDACTIONS.md.
(This is the human door into the raw dump. The body stays machine-first.)
\n" }